|
2 | 2 |
|
3 | 3 |  [](https://community.internetfreedomfestival.org/community/channels/outline-community) [](https://www.reddit.com/r/outlinevpn/) |
4 | 4 |
|
5 | | -This repository has all the code needed to create and manage Outline servers on |
6 | | -DigitalOcean. An Outline server runs instances of Shadowsocks proxies and |
7 | | -provides an API used by the Outline Manager application. |
| 5 | +Outline Server is the component that provides the Shadowsocks service (via [outline-ss-server](https://github.com/Jigsaw-Code/outline-ss-server/)) and a service management API. You can deploy this server directly following simple instructions in this repository, or if you prefer a ready-to-use graphical interface you can use the [Outline Manager](https://github.com/Jigsaw-Code/outline-apps/). |
8 | 6 |
|
9 | | -Go to https://getoutline.org for ready-to-use versions of the software. **To join our Outline Community, [sign up for the IFF Mattermost](https://internetfreedomfestival.org/wiki/index.php/IFF_Mattermost).** |
| 7 | +**Components:** |
10 | 8 |
|
11 | | -## Components |
| 9 | +- **Outline Server** ([`src/shadowbox`](src/shadowbox)): The core proxy server that runs and manages [outline-ss-server](https://github.com/Jigsaw-Code/outline-ss-server/), a Shadowsocks backend. It provides a REST API for access key management. |
12 | 10 |
|
13 | | -The system comprises the following components: |
| 11 | +- **Metrics Server** ([`src/metrics_server`](src/metrics_server)): A REST service for optional, anonymous metrics sharing. |
14 | 12 |
|
15 | | -- **Outline Server**: a proxy server that runs a Shadowsocks instance for each |
16 | | - access key and a REST API to manage the access keys. The Outline Server runs |
17 | | - in a Docker container in the host machine. |
| 13 | +**Join the Outline Community** by signing up for the [IFF Mattermost](https://wiki.digitalrights.community/index.php?title=IFF_Mattermost)! |
18 | 14 |
|
19 | | - See [`src/shadowbox`](src/shadowbox) |
| 15 | +## Shadowsocks and Anti-Censorship |
20 | 16 |
|
21 | | -- **Outline Manager:** an [Electron](https://electronjs.org/) application that |
22 | | - can create Outline Servers on the cloud and talks to their access key |
23 | | - management API to manage who has access to the server. |
| 17 | +Outline's use of Shadowsocks means it benefits from ongoing improvements that strengthen its resistance against detection and blocking. |
24 | 18 |
|
25 | | - See [`src/server_manager`](src/server_manager) |
| 19 | +**Key Protections:** |
26 | 20 |
|
27 | | -- **Metrics Server:** a REST service that the Outline Server talks to |
28 | | - if the user opts-in to anonymous metrics sharing. |
| 21 | +- **AEAD ciphers** are mandatory. |
| 22 | +- **Probing resistance** mitigates detection techniques. |
| 23 | +- **Protection against replayed data.** |
| 24 | +- **Variable packet sizes** to hinder identification. |
29 | 25 |
|
30 | | - See [`src/metrics_server`](src/metrics_server) |
| 26 | +See [Shadowsocks resistance against detection and blocking](docs/shadowsocks.md). |
31 | 27 |
|
32 | | -## Code Prerequisites |
| 28 | +## Installation |
33 | 29 |
|
34 | | -In order to build and run the code, you need the following installed: |
| 30 | +**Prerequisites** |
35 | 31 |
|
36 | 32 | - [Node](https://nodejs.org/en/download/) LTS (`lts/hydrogen`, version `18.16.0`) |
37 | 33 | - [NPM](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) (version `9.5.1`) |
38 | | -- Manager-specific |
39 | | - - [Wine](https://www.winehq.org/download), if you would like to generate binaries for Windows. |
40 | | -- Server-specific |
41 | | - - [Docker](https://docs.docker.com/engine/install/), to build the Docker image and to run the integration test. |
42 | | - - [docker-compose](https://docs.docker.com/compose/install/), to run the integration test. |
43 | 34 |
|
44 | | -> 💡 NOTE: if you have `nvm` installed, run `nvm use` to switch to the correct node version! |
| 35 | +1. **Install dependencies** |
45 | 36 |
|
46 | | -Install dependencies with: |
| 37 | + ```sh |
| 38 | + npm install |
| 39 | + ``` |
47 | 40 |
|
48 | | -```sh |
49 | | -npm install |
50 | | -``` |
| 41 | +1. **Start the server** |
51 | 42 |
|
52 | | -This project uses [NPM workspaces](https://docs.npmjs.com/cli/v7/using-npm/workspaces/). |
| 43 | + ```sh |
| 44 | + npm run action shadowbox/server/start |
| 45 | + ``` |
53 | 46 |
|
54 | | -## Build System |
| 47 | + Exploring further options: |
55 | 48 |
|
56 | | -We have a very simple build system based on package.json scripts that are called using `npm run` |
57 | | -and a thin wrapper for what we call build "actions". |
| 49 | + - **Refer to the README:** Find additional configuration and usage options in the core server's [`README`](src/shadowbox/README.md). |
| 50 | + - **Learn about the build system:** For in-depth build system information, consult the [contributing guide](CONTRIBUTING.md). |
58 | 51 |
|
59 | | -We've defined a package.json script called `action` whose parameter is a relative path: |
| 52 | +1. **To clean up** |
60 | 53 |
|
61 | | -```shell |
62 | | -npm run action $ACTION |
63 | | -``` |
64 | | - |
65 | | -This command will define a `run_action()` function and call `${ACTION}.action.sh`, which must exist. |
66 | | -The called action script can use `run_action` to call its dependencies. The $ACTION parameter is |
67 | | -always resolved from the project root, regardless of the caller location. |
68 | | - |
69 | | -The idea of `run_action` is to keep the build logic next to where the relevant code is. |
70 | | -It also defines two environmental variables: |
71 | | - |
72 | | -- ROOT_DIR: the root directory of the project, as an absolute path. |
73 | | -- BUILD_DIR: where the build output should go, as an absolute path. |
74 | | - |
75 | | -> ⚠️ To find all the actions in this project, run `npm run action:list` |
76 | | -
|
77 | | -### Build output |
78 | | - |
79 | | -Building creates the following directories under `build/`: |
80 | | - |
81 | | -- `web_app/`: The Manager web app. |
82 | | - - `static/`: The standalone web app static files. This is what one deploys to a web server or runs with Electron. |
83 | | -- `electron_app/`: The launcher desktop Electron app |
84 | | - - `static/`: The Manager Electron app to run with the electron command-line |
85 | | - - `bundled/`: The Electron app bundled to run standalone on each platform |
86 | | - - `packaged/`: The Electron app bundles packaged as single files for distribution |
87 | | -- `invite_page`: the Invite Page |
88 | | - - `static`: The standalone static files to be deployed |
89 | | -- `shadowbox`: The Proxy Server |
90 | | - |
91 | | -The directories have subdirectories for intermediate output: |
92 | | - |
93 | | -- `ts/`: Autogenerated Typescript files |
94 | | -- `js/`: The output from compiling Typescript code |
95 | | -- `browserified/`: The output of browserifying the JavaScript code |
96 | | - |
97 | | -To clean up: |
98 | | - |
99 | | -``` |
100 | | -npm run clean |
101 | | -``` |
102 | | - |
103 | | -## Shadowsocks Resistance Against Detection and Blocking |
104 | | - |
105 | | -Shadowsocks used to be blocked in some countries, and because Outline uses Shadowsocks, there has been skepticism about Outline working in those countries. In fact, people have tried Outline in the past and had their servers blocked. |
106 | | - |
107 | | -However, since the second half of 2020 things have changed. The Outline team and Shadowsocks community made a number of improvements that strengthened Shadowsocks beyond the censor's current capabilities. |
108 | | - |
109 | | -As shown in the research [How China Detects and Blocks Shadowsocks](https://gfw.report/talks/imc20/en/), the censor uses active probing to detect Shadowsocks servers. The probing may be triggered by packet sniffing, but that's not how the servers are detected. |
110 | | - |
111 | | -Even though Shadowsocks is a standard, it leaves a lot of room for choices on how it's implemented and deployed. |
112 | | - |
113 | | -First of all, you **must use AEAD ciphers**. The old stream ciphers are easy to break and manipulate, exposing you to simple detection and decryption attacks. Outline has banned all stream ciphers, since people copy old examples to set up their servers. The Outline Manager goes further and picks the cipher for you, since users don't usually know how to choose a cipher, and it generates a long random secret, so you are not vulnerable to dictionary-based attacks. |
114 | | - |
115 | | -Second, you need **probing resistance**. Both shadowsocks-libev and Outline have added that. The research [Detecting Probe-resistant Proxies](https://www.ndss-symposium.org/ndss-paper/detecting-probe-resistant-proxies/) showed that, in the past, an invalid byte would trigger different behaviors whether it was inserted in positions 49, 50 or 51 of the stream, which is very telling. That behavior is now gone, and the censor can no longer rely on that. |
116 | | - |
117 | | -Third, you need **protection against replayed data**. Both shadowsocks-libev and Outline have added such protection, which you may need to enable explicitly on ss-libev, but it's the default on Outline. |
118 | | - |
119 | | -Fourth, Outline and clients using shadowsocks-libev now **merge the SOCKS address and the initial data** in the same initial encrypted frame, making the size of the first packet variable. Before the first packet only had the SOCKS address, with a fixed size, and that was a giveaway. |
120 | | - |
121 | | -The censors used to block Shadowsocks, but Shadowsocks has evolved, and in 2021, it was ahead again in the cat and mouse game. |
122 | | - |
123 | | -In 2022 China started blocking seemingly random traffic ([report](https://www.opentech.fund/news/exposing-the-great-firewalls-dynamic-blocking-of-fully-encrypted-traffic/)). While there is no evidence they could detect Shadowsocks, the protocol ended up blocked. |
124 | | - |
125 | | -As a reponse, we [added a feature to the Outline Client](https://github.com/Jigsaw-Code/outline-client/pull/1454) that allows service managers to specify in the access key a prefix to be used in the Shadowsocks initialization, which can be used to bypass the blocking in China. |
126 | | - |
127 | | -Shadowsocks remains our protocol of choice because it's simple, well understood and very performant. Furthermore, it has an enthusiastic community of very smart people behind it. |
| 54 | + ```sh |
| 55 | + npm run clean |
| 56 | + ``` |
0 commit comments