Skip to content

Commit

Permalink
Improve snowflake standalone guides
Browse files Browse the repository at this point in the history
  • Loading branch information
Gus committed Feb 5, 2024
1 parent 1264bf3 commit 8679f4e
Show file tree
Hide file tree
Showing 7 changed files with 275 additions and 220 deletions.
128 changes: 0 additions & 128 deletions content/relay/setup/snowflake/ansible/contents.lr
View file

This file was deleted.

4 changes: 0 additions & 4 deletions content/relay/setup/snowflake/standalone/ansible/contents.lr
View file
Original file line number Diff line number Diff line change
Expand Up @@ -122,7 +122,3 @@ The playbook below has a limit of 300 concurrent clients:
```

**Note:** This Ansible role variable isn't available for FreeBSD.
---
_hidden: no
---
_discoverable: no
91 changes: 3 additions & 88 deletions content/relay/setup/snowflake/standalone/contents.lr
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ title: Standalone Snowflake proxy
---
body:

This guide will help you set up a standalone Snowflake proxy on a server to help censored users connect to the Tor network.
This guide will help you set up a standalone Snowflake proxy to help censored users connect to the Tor network.
The only requirements are internet connectivity, however one of the main advantages of standalone Snowflake proxies is that they can be installed on servers and offer a higher bandwidth and more reliable option for users behind restrictive NATs and firewalls.
Therefore, we especially recommend:
1. 24/7 Internet connectivity
Expand All @@ -15,93 +15,8 @@ The properties you are looking for are address-independent mapping and either ad
3. A server behind no or unrestricted NAT, with incoming UDP on the whole port range of `cat /proc/sys/net/ipv4/ip_local_port_range` open (or the range set using the optional `-ephemeral-ports-range` flag).

There are several ways to setup and run a standalone snowflake proxy.

### Docker setup

You must first have [Docker](https://docs.docker.com/engine/install/) and [docker-compose](https://docs.docker.com/compose/install/) installed.

We have a [Docker image](https://hub.docker.com/r/thetorproject/snowflake-proxy) to ease the setup of a snowflake proxy.
First [download docker-compose.yml](https://gitlab.torproject.org/tpo/anti-censorship/docker-snowflake-proxy/raw/main/docker-compose.yml).
Then, deploy the proxy by running:
```
docker-compose up -d snowflake-proxy
```

You should now see the output:
```
Creating snowflake-proxy ... done
```
and your proxy is up and running!

The [docker-compose.yml](https://gitlab.torproject.org/tpo/anti-censorship/docker-snowflake-proxy/raw/main/docker-compose.yml) contains a `watchtower` container, configured to automatically check for updates to the snowflake docker container every day, download them and run them.
So if you are using that, your snowflake proxy will stay updated automatically!
Otherwise, you will need to periodically pull the latest container and restart it manually.

### Ansible

There is now an [Ansible role](https://galaxy.ansible.com/nvjacobo/snowflake) to install a Snowflake proxy on Debian, Fedora, Arch Linux, FreeBSD and Ubuntu created by Jacobo Nájera.
Follow the guide to run a [Snowflake with Ansible](/relay/setup/snowflake/standalone/ansible).

### Compiling and running from source

1. First you will need to install and configure the Go compiler to build the standalone proxy from source code.
Please login using a user account with `sudo` rights or directly with `root` (in the later case omit the `sudo` part in the following commands).
If you are running Ubuntu or Debian, you can install Go by executing `sudo apt install golang`.
If you are using Fedora, Red Hat or Amazon Linux with `sudo yum install golang` or `sudo dnf install golang`.
Otherwise visit https://golang.org/dl/.
You will need Go 1.21 or newer to run the Snowflake proxy.
You can check your installed version using the command `go version`.

2. Second you need the git client to download the Snowflake source code.
Please login using a user account with `sudo` rights or directly with `root` (in the later case omit the `sudo` part of the following commands).
If you are running Ubuntu or Debian, you can install git by executing `sudo apt install git`.
If you are using Fedora, Red Hat or Amazon Linux with `sudo yum install git` or `sudo dnf install git`.
Otherwise consult the documentation for your operating system.

3. Please execute the following steps with the user account under which the proxy should be executed.
Don't use `root`.
It's recommended to create a separate `snowflake` account with restricted rights on the system.

4. Clone the [source code](#source-code).
```
git clone https://gitlab.torproject.org/tpo/anti-censorship/pluggable-transports/snowflake.git
```
5. Build the Snowflake proxy.
```
cd snowflake/proxy
go build
```

6. Run the Snowflake proxy.
```
nohup ./proxy &
```
If you want to save the proxy output to a logfile, you can use:
```
nohup ./proxy >snowflake.log 2>&1 &
```

7. Make sure the proxy is started after a reboot of the system:
```
crontab -e
```
Enter the following line (example, adapt paths to your situation)
```
@reboot nohup /home/snowflake/snowflake/proxy/proxy > /home/snowflake/snowflake/proxy/snowflake.log 2>&1 &
```
Please verify if this is working by rebooting the system and checking the log.
On some Linux installations this might not work.

To keep your snowflake proxy updated, execute the following commands every few weeks (login with the user account you used during installing the proxy):

```
kill -9 $(pidof proxy)
cd snowflake/
git pull
cd proxy
go build
nohup ./proxy >snowflake.log 2>&1 &
```
Please choose your preferred platform below.
If you need help to install and operate your Snowflake proxy, visit the [Tor Forum](https://forum.torproject.org/tag/snowflake).

---
key: 1
Expand Down
59 changes: 59 additions & 0 deletions content/relay/setup/snowflake/standalone/debian/contents.lr
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,59 @@
_model: page
---
color: primary
---
title: Debian
---
key: 4
---
html: two-columns-page.html
---
subtitle: How to run a standalone Snowflake proxy on Debian
---
section_id: snowflake-operations
---
section: Snowflake operations
---
body:

This guide will walk you through the installation, operation, and maintenance of [Snowflake](https://snowflake.torproject.org) proxy to contribute to the Tor Project's anti-censorship efforts.
Snowflake proxy can be easily installed as a package on Debian-based systems (Debian 12 - bookworm).

### 1. Installation

Open your terminal and execute the following command:

```
sudo apt install snowflake-proxy
```

### 2. Operating snowflake proxy

The snowflake proxy service should start automatically after installation.
You can manage the service with systemd commands:

```
sudo systemctl start snowflake-proxy
```

To enable snowflake proxy to automatically start on on boot:
```
sudo systemctl enable snowflake-proxy
```

To check the current status of your snowflake proxy:
```
sudo systemctl status snowflake-proxy
```

### 3. Monitoring logs

Keeping an eye on the operation logs can help troubleshoot issues or confirm the proxy's activity:
```
sudo journalctl -u snowflake-proxy
```

### 4. Enable Automatic Software Updates

One of the most important things to keep your snowflake proxy secure is to install security updates timely and ideally automatically so you can not forget about it. Follow the instructions to enable [automatic software updates](relay/setup/guard/debian-ubuntu/updates/) for your operating system.

68 changes: 68 additions & 0 deletions content/relay/setup/snowflake/standalone/docker/contents.lr
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,68 @@
_model: page
---
color: primary
---
title: Docker setup
---
key: 2
---
html: two-columns-page.html
---
subtitle: How to run a standalone Snowflake proxy with Docker
---
section_id: snowflake-operations
---
section: Snowflake operations
---
body:

This guide will help you set up a standalone [Snowflake](https://snowflake.torproject.org) proxy using Docker to help censored users connect to the Tor network.
We have a [Docker image](https://hub.docker.com/r/thetorproject/snowflake-proxy) to ease the setup of a Snowflake proxy.

### 1. Install Docker

The instructions in this step are for Debian-based systems, but you can find [Docker instructions](https://docs.docker.com/get-docker/) for other supported platforms.

Open a terminal and run these commands:
```
$ sudo apt install curl sudo
$ curl -fsSL https://get.docker.com -o get-docker.sh
$ sudo sh ./get-docker.sh
```

### 2. Download the docker compose file

Download the [docker-compose.yml](https://gitlab.torproject.org/tpo/anti-censorship/docker-snowflake-proxy/raw/main/docker-compose.yml) configuration file.
Run the command to download it:
```
$ wget https://gitlab.torproject.org/tpo/anti-censorship/docker-snowflake-proxy/raw/main/docker-compose.yml
```
Then, deploy the proxy by running:
```
docker compose up -d snowflake-proxy
```
This command starts the Snowflake proxy in detached mode.
You should now see the output:
```
Creating snowflake-proxy ... done
```
and your proxy is up and running!

### 3. Checking your Docker logs

To access your Snowflake proxy logs, first find the container ID number.
Run the command:
```
$ docker ps
```
Your Snowflake container ID is on the same line of `thetorproject/snowflake-proxy:latest`.
Replace the container ID below with yours and run the command:
```
$ docker logs -f 42fb82372340
```

### 4. Automatic updates with Watchtower

The [docker-compose.yml](https://gitlab.torproject.org/tpo/anti-censorship/docker-snowflake-proxy/raw/main/docker-compose.yml) file contains a `watchtower` container, configured to automatically check for updates to the snowflake docker container every day, download them and run them.
So if you are using that, your snowflake proxy will stay updated automatically!
Otherwise, you will need to periodically pull the latest container and restart it manually.
Loading

0 comments on commit 8679f4e

Please sign in to comment.