outlinefoundation/tunnel-server

Outline includes a defense against client replay attacks by storing a 32-bit checksum of every valid incoming handshake in a hash table. This feature is enabled by default. If you are running outline-ss-server directly, you can manually configure the size of the replay history using the --replay_history flag.

Each checksum consumes approximately 20 bytes of memory. For example, setting it to 10000 will store 10,000 checksums.

# Example: Invoking outline-ss-server with a specific replay history size
./outline-ss-server --replay_history 10000

The outline-ss-server command starts the Shadowsocks backend. It supports multiple users on a single port by attempting all provided credentials until one succeeds. You can enable replay protection, configure Prometheus metrics, and provide MMDB files for geographic/ASN metrics breakdown.

Recommended production command structure:

outline-ss-server -replay_history=10000 -metrics=127.0.0.1:9091 -config=$CONFIG_YML -ip_country_db=$COUNTRY_MMDB -ip_asn_db=$ASN_MMDB

Use the task runner to execute the project's test suite and benchmarks.

To benchmark the cipher finding code specifically, use go test with profiling enabled:

go test -cpuprofile cpu.prof -memprofile mem.prof -bench . -benchmem -run=^$ github.com/Jigsaw-Code/outline-ss-server/shadowsocks

You can inspect the resulting profiles using go tool pprof:

go tool pprof cpu.prof
# Inside pprof, type 'web' to view the graph

go run github.com/go-task/task/v3/cmd/task test

To use the Outline Shadowsocks backend within Caddy, you must build a custom Caddy binary using xcaddy that includes the outlinecaddy module along with the caddy-l4 and caddy_yaml_adapter dependencies. Once built, you can run the server using a YAML configuration file.

After starting the server, you can verify the Shadowsocks backend is working by using the Outline SDK to fetch a page over the configured transport.

xcaddy build \
  --with github.com/iamd3vil/caddy_yaml_adapter \
  --with github.com/mholt/caddy-l4 \
  --with github.com/Jigsaw-Code/outline-ss-server/outlinecaddy
./caddy run --config examples/simple.yaml --adapter yaml --watch

For development purposes, you can run the Caddy module directly from the Go source code. Use the nomysql build tag to exclude MySQL dependencies.

go run -tags nomysql ./cmd/caddy run \
  --adapter yaml \
  --config examples/simple.yml \
  --watch

A ConnectionHandler is a named, reusable connection handler designed to be configured within the Outline app and shared across different applications (e.g., sharing a Shadowsocks handler between the layer4 app and an HTTP app).

It works by wrapping a layer4.NextHandler. By assigning a Name to the handler, you can reference the same underlying service configuration in multiple places in your Caddy configuration, ensuring consistency across different protocol stacks.

To use it, define a ConnectionHandler with a name and provide the raw JSON configuration for the underlying handler in the handle field.

{
  "name": "my-shared-shadowsocks",
  "handle": {
    ""// configuration for the actual layer4 handler"" : ""
  }
}

The OutlineHandler identifies the underlying protocol of a connection and sets a context variable layer4.handlers.outline.cxtype. This allows downstream handlers to know how to process the connection.

Supported types:

• stream: Assigned when the connection implements transport.StreamConn.
• packet: Assigned when the connection implements net.Conn (standard network connection).

These are represented by the ConnectionType type constants:

• StreamConnectionType ("stream")
• PacketConnectionType ("packet")

The OutlineServer supports hot-swapping configurations without stopping the entire process. When loadConfig is called (either manually or via SIGHUP):

1. The new configuration is read and validated.
2. New listeners (TCP, UDP, or Web) are created for the new configuration.
3. The old configuration's stopConfig function is called to close the previous listeners.
4. The server's internal stopConfig pointer is updated to the new one.

This approach ensures that there is a period where both old and new listeners coexist, minimizing downtime during configuration updates.

After running the Caddy server with the Outline module, use the following command to confirm you can successfully fetch a page over the Shadowsocks transport. Replace the transport string with your specific protocol and credentials.

go run golang.getoutline.org/sdk/x/examples/fetch \
  -transport "ss://chacha20-ietf-poly1305:Secret1@:9000" \
  http://ipinfo.io