outline-server/src/shadowbox

Outline Server

The internal name for the Outline server is "Shadowbox". It is a server set up that runs a user management API and starts Shadowsocks instances on demand.

It aims to make it as easy as possible to set up and share a Shadowsocks server. It's managed by the Outline Manager and used as proxy by the Outline client apps. Shadowbox is also compatible with standard Shadowsocks clients.

Self-hosted installation

To install and run Shadowbox on your own server, run

bash -c "$(wget -qO- https://raw.githubusercontent.com/Jigsaw-Code/outline-server/master/src/server_manager/install_scripts/install_server.sh)"

Use bash -x instead at the end of the command if you need to debug the installation.

Running from source code

Prerequisites

Besides Node and Yarn, you will also need:

1. Docker 1.13+
2. docker-compose 1.11+

Run docker info and make sure Storage Driver is devicemapper. If it is not, you can override it by editting /etc/default/docker or by passing another storage driver in the daemon commandline:

sudo dockerd --storage-driver=devicemapper

Running Shadowbox as a Node.js app

Build the server as a Node.js app:

yarn do shadowbox/server/build

The output will be at build/shadowbox/app.

You can see how to run the server at shadowbox/server/run_action.sh.

Running Shadowbox as a Docker container

NOTE: This does not currently work in Docker on Mac due to use of --host=net and integrity checks failing. For now, please see the Manual testing section below.

With docker command

Build the outline/shadowbox Docker image:

yarn do shadowbox/docker/build

Run server:

yarn do shadowbox/docker/run

Debug image:

docker run --rm -it --entrypoint=sh outline/shadowbox

Or a running container:

docker exec -it shadowbox sh

Delete dangling images:

docker rmi $(docker images -f dangling=true -q)

Access Keys Management API

In order to utilize the Management API, you'll need to know the apiUrl for your Outline server. You can obtain this information from the 'access.txt' file under the 'shadowbox' directory of your server. An example apiUrl is: https://1.2.3.4:1234/3pQ4jf6qSr5WVeMO0XOo4z.

Start by storing the apiURL you see see in that file, as a variable. For example:

API_URL=https://1.2.3.4:1234/3pQ4jf6qSr5WVeMO0XOo4z

You can then perform the following operations on the server, remotely.

List users

curl --insecure $API_URL/access-keys/

Create a user

curl --insecure -X POST $API_URL/access-keys

Rename a user (e.g. rename user ID 2 to 'albion')

curl --insecure -X PUT curl -F 'name=albion' $API_URL/access-keys/2/name

Remove a user (e.g. remove user ID 2)

curl --insecure -X DELETE $API_URL/access-keys/2

Example output

$ API_URL=https://1.2.3.4:1234/3pQ4jf6qSr5WVeMO0XOo4z
$ curl --insecure $API_URL/access-keys
{"users":[]}

$ curl --insecure -X POST $API_URL/access-keys
{"id":"0","password":"Nm9wtQkPeshs","port":34180}

$ curl --insecure -X POST $API_URL/access-keys
{"id":"1","password":"32mW3jhuhBGv","port":55625}

$ curl --insecure -X POST $API_URL/access-keys
{"id":"2","password":"jFOKrJcpbgIb","port":15884}

$ curl --insecure $API_URL/access-keys
{"users":[{"id":"0","password":"Nm9wtQkPeshs","port":34180},{"id":"1","password":"32mW3jhuhBGv","port":55625},{"id":"2","password":"jFOKrJcpbgIb","port":15884}]}

$ curl --insecure -X DELETE $API_URL/access-keys/0 -v
* Hostname was NOT found in DNS cache
*   Trying ::1...
* Connected to 1.2.3.4 (::1) port 1234 (#0)
> DELETE /access-keys/0 HTTP/1.1
> User-Agent: curl/7.35.0
> Host: 1.2.3.4:1234
> Accept: */*
>
< HTTP/1.1 204 No Content
< Date: Fri, 03 Feb 2017 22:46:39 GMT
< Connection: keep-alive
<
* Connection #0 to host 1.2.3.4 left intact

$ curl --insecure $API_URL/access-keys
{"users":[{"id":"1","password":"32mW3jhuhBGv","port":55625},{"id":"2","password":"jFOKrJcpbgIb","port":15884}]}

Testing

Manual

After building a docker image with some local changes, upload it to your favorite registry (e.g. Docker Hub, quay.io, etc.).

Then set your SB_IMAGE environment variable to point to the image you just uploaded (e.g. export SB_IMAGE=yourdockerhubusername/shadowbox) and run yarn do server_manager/electron_app/run and your droplet should be created with your modified image.

Automated

To run the integration test:

yarn do shadowbox/integration_test/run

This will set up three containers and two networks:

client <-> shadowbox <-> target

client can only access target via shadowbox. We create a user on shadowbox then connect using the Shadowsocks client.

To test clients that rely on fetching a docker image from Dockerhub, you can push an image to your account and modify the client to use your image. To push your own image:

yarn shadowbox_docker_build && docker tag quay.io/outline/shadowbox $USER/shadowbox && docker push $USER/shadowbox

If you need to test an unsigned image (e.g. your dev one):

DOCKER_CONTENT_TRUST=0 SHADOWBOX_IMAGE=$USER/shadowbox yarn do shadowbox/integration_test/run

You can add tags if you need different versions in different clients.