Shadowsocks-over-WebSockets

Outline Client v1.15.0+.

This tutorial provides a detailed walkthrough to help you implement Shadowsocks-over-WebSockets, a powerful technique for bypassing censorship in environments where regular Shadowsocks connections are blocked. By encapsulating Shadowsocks traffic within WebSockets, you can disguise it as standard web traffic, enhancing resilience and accessibility.

Step 1: Configure and Run an Outline Server

Create a new config.yaml file with the following configuration:

web:
  servers:
    - id: server1
      listen:
        - "127.0.0.1:WEB_SERVER_PORT"

services:
  - listeners:
      - type: websocket-stream
        web_server: server1
        path: "/TCP_PATH"
      - type: websocket-packet
        web_server: server1
        path: "/UDP_PATH"
    keys:
      - id: 1
        cipher: chacha20-ietf-poly1305
        secret: SHADOWSOCKS_SECRET

Download the latest outline-ss-server and run it using the created configuration:

outline-ss-server -config=config.yaml

Step 2: Expose the Web Server

To make your WebSocket web server publicly accessible, you'll need to expose it to the internet and configure TLS. You have several options for achieving this. You can use a local web server like Caddy, nginx or Apache, ensuring it has a valid TLS certificate, or employ a tunneling service such as Cloudflare Tunnel or ngrok.

Example using TryCloudflare

For this example, we'll demonstrate using TryCloudflare to create a quick tunnel. This provides a convenient and secure way to expose your local web server without opening inbound ports.

  1. Download and install cloudflared.

  2. Create a tunnel pointing to your local web server port:

    cloudflared tunnel --url http://127.0.0.1:WEB_SERVER_PORT

Cloudflare will provide a subdomain (e.g., acids-iceland-davidson-lb.trycloudflare.com) to access your WebSocket endpoint and automatically handle TLS. Make note of this subdomain, as you'll need it later.

Step 3: Create a Dynamic Access Key

Generate a client access key YAML file for your users using the Access Key Configuration format and include the WebSocket endpoints previously configured on the server side:

transport:
  $type: tcpudp

  tcp:
    $type: shadowsocks

    endpoint:
      $type: websocket
      url: wss://DOMAIN/TCP_PATH
    cipher: chacha20-ietf-poly1305
    secret: SHADOWSOCKS_SECRET

  udp:
    $type: shadowsocks

    endpoint:
      $type: websocket
      url: wss://DOMAIN/UDP_PATH
    cipher: chacha20-ietf-poly1305
    secret: SHADOWSOCKS_SECRET

After generating the dynamic access key YAML file, you need to get it to your users. You can host the file on a static web hosting service or dynamically generate it. Learn more about how to use Dynamic Access Keys.

Step 4: Connect with the Outline Client

Use one of the official Outline Client applications (versions 1.15.0+) and add your newly created dynamic access key as a server entry. Click Connect to start tunneling to your server using the Shadowsocks-over-Websocket configuration.

Use a tool like IPInfo to verify you are now browsing the internet via your Outline server.