Skip to content

config.md

Latest commit

 

History

History
419 lines (296 loc) · 11.9 KB

config.md

File metadata and controls

419 lines (296 loc) · 11.9 KB
Raw

Outline Config Reference

Outline uses a YAML-based configuration to define VPN parameters and handle TCP/UDP traffic. The configuration supports composability at multiple levels, enabling flexible and extensible setups.

The top-level configuration specifies a TunnelConfig.

Examples

A typical Shadowsocks configuration will look like this:

transport:
  $type: tcpudp

  tcp:
    $type: shadowsocks
    endpoint: ss.example.com:4321
    cipher: chacha20-ietf-poly1305
    secret: SECRET
    prefix: "POST "

  udp:
    $type: shadowsocks
    endpoint: ss.example.com:4321
    cipher: chacha20-ietf-poly1305
    secret: SECRET

Note how we can now have TCP and UDP running on different ports or endpoints.

You can leverage YAML anchors and the << merge key to avoid duplication:

transport:
  $type: tcpudp

  tcp:
    <<: &shared
      $type: shadowsocks
      endpoint: ss.example.com:4321
      cipher: chacha20-ietf-poly1305
      secret: SECRET
    prefix: "POST "

  udp: *shared

It's now possible to compose strategies and do multi-hops:

transport:
  $type: tcpudp

  tcp:
    $type: shadowsocks

    endpoint:
      $type: dial
      address: exit.example.com:4321
      dialer:
        $type: shadowsocks
        address: entry.example.com:4321
        cipher: chacha20-ietf-poly1305
        secret: ENTRY_SECRET

    cipher: chacha20-ietf-poly1305
    secret: EXIT_SECRET

  udp: *shared

In case of blocking of "look-like-nothing" protocols like Shadowsocks, you can use Shadowsocks over Websockets. See the server examnple configuration on how to deploy it. A client configuration will look like:

transport:
  $type: tcpudp
  tcp:
    $type: shadowsocks
    endpoint:
        $type: websocket
        url: wss://legendary-faster-packs-und.trycloudflare.com/SECRET_PATH/tcp
    cipher: chacha20-ietf-poly1305
    secret: SS_SECRET

  udp:
    $type: shadowsocks
    endpoint:
        $type: websocket
        url: wss://legendary-faster-packs-und.trycloudflare.com/SECRET_PATH/udp
    cipher: chacha20-ietf-poly1305
    secret: SS_SECRET

Note that the Websocket endpoint can, in turn, take an endpoint, which can be leveraged to bypass DNS-based blocking:

transport:
  $type: tcpudp
  tcp:
    $type: shadowsocks
    endpoint:
        $type: websocket
        url: wss://legendary-faster-packs-und.trycloudflare.com/SECRET_PATH/tcp
        endpoint: cloudflare.net:443
    cipher: chacha20-ietf-poly1305
    secret: SS_SECRET

  udp:
    $type: shadowsocks
    endpoint:
        $type: websocket
        url: wss://legendary-faster-packs-und.trycloudflare.com/SECRET_PATH/udp
        endpoint: cloudflare.net:443
    cipher: chacha20-ietf-poly1305
    secret: SS_SECRET

Note that Websockets is not yet supported on Windows. In order to have a single config for all platforms, use a first-supported for backwards-compatibility:

transport:
  $type: tcpudp
  tcp:
    $type: shadowsocks
    endpoint:
      $type: first-supported
      options:
        - $type: websocket
          url: wss://legendary-faster-packs-und.trycloudflare.com/SECRET_PATH/tcp
        - ss.example.com:4321
    cipher: chacha20-ietf-poly1305
    secret: SS_SECRET

  udp:
    $type: shadowsocks
    endpoint:
      $type: first-supported
      options:
        - $type: websocket
          url: wss://legendary-faster-packs-und.trycloudflare.com/SECRET_PATH/udp
        - ss.example.com:4321
    cipher: chacha20-ietf-poly1305
    secret: SS_SECRET

In case the count of users is needed to have an exact estimate of the sessions, a reporting server can be used for that. This feature is currently experimental.

transport:
  $type: tcpudp
  tcp:
    <<: &shared
      $type: shadowsocks
      endpoint: ss.example.com:4321
      cipher: chacha20-ietf-poly1305
      secret: SECRET
    prefix: "POST "
  udp: *shared

reporter:
  $type: http
  request:
    # URL is the only required field.
    url: https://your-callback-server.com/outline_callback
    method: POST  # This is the default, no need to specify
    headers:
      Content-Type: [application/json]
      Authorization: [Bearer SECRET]
    body: '{"foo": "bar"}'
  # Optional. If not specified reporting happens once at the start of the session.
  interval: 24h
  # Optional. If enabled, the HTTP client will remember cookies across sessions.
  enable_cookies: true

Tunnels

TunnelConfig

Tunnel is the top-level object in the Outline configuration returned by Dynamic Access Keys. It specifies how the VPN should be configured.

Format: ExplicitTunnelConfig | LegacyShadowsocksConfig | LegacyShadowsocksURI

ExplicitTunnelConfig

Format: struct

Fields:

  • transport (TransportConfig): the transport to use to exchange packages with the target destination
  • error (struct): information to communicate to the user in case of service error (e.g. key expired, quota exhausted)
    • message (string): user-friendly message to display to the user
    • details (string): message to display when the user opens the error details. Helpful for troubleshooting.

Fields error and transport are mutually exclusive.

Successful example:

transport:
  $type: tcpudp
  tcp:
    ...  # Stream Dialer for TCP
  udp:
    ...  # Packet Listener for UDP

Error example:

error:
  message: Quota exceeded
  details: Used 100GB out of 100GB

Transports

TransportConfig

Specifies how packets should be exchanged with the target destination.

Format: Interface

Supported Interface types:

TCPUDPConfig

TCPUDPConfig allows for setting separate TCP and UDP strategies.

Format: struct

Fields:

Example sending TCP and UDP to different endpoints:

tcp:
  $type: shadowsocks
  endpoint: ss.example.com:80
  <<: &cipher
    cipher: chacha20-ietf-poly1305
    secret: SECRET
  prefix: "POST "

udp:
  $type: shadowsocks
  endpoint: ss.example.com:53
  <<: *cipher

Endpoints

Endpoints establish connections to a fixed endpoint. It's preferable over Dialers since it allows for endpoint-specific optimizations. There are Stream and Packet Endpoints.

EndpointConfig

Format: string | Interface

The string Endpoint is the host:port address of the desired endpoint. The connection is established using the default Dialer.

Supported Interface types for Stream and Packet Endpoints:

DialEndpointConfig

Establishes connections by dialing a fixed address. It can take a dialer, which allows for composition of strategies.

Format: struct

Fields:

  • address (string): the endpoint address to dial
  • dialer (DialerConfig): the dialer to use to dial the address

WebsocketEndpointConfig

Tunnels stream and packet connections to an endpoint over Websockets.

For stream connections, each write is turned into a Websocket message. For packet connections, each packet is turned into a Websocket message.

Format: struct

Fields:

  • url (string): the URL for the Websocket endpoint. The schema must be https or wss for Websocket over TLS, and http or ws for plaintext Websocket.
  • endpoint (EndpointConfig): the web server endpoint to connect to. If absent, is connects to the address specified in the URL.

Dialers

Dialers establishes connections given an endpoint address. There are Stream and Packet Dialers.

DialerConfig

Format: null | Interface

The null (absent) Dialer means the default Dialer, which uses direct TCP connections for Stream and direct UDP connections for Packets.

Supported Interface types for Stream and Packer Dialers:

Packet Listeners

A Packet Listener establishes an unbounded packet connection that can be used to send packets to multiple destinations.

PacketListenerConfig

Format: null | Interface

The null (absent) Packet Listener means the default Packet Listener, which is a UDP Packet Listener.

Supported Interface types:

Strategies

Shadowsocks

LegacyShadowsocksConfig

LegacyShadowsocksConfig represents a Tunnel that uses Shadowsocks as the transport. It implements the legacy format for backwards-compatibility.

Format: struct

Fields:

  • server (string): the host to connect to
  • server_port (number): the port number to connect to
  • method (string): the AEAD cipher to use
  • password (string): used to generate the encryption key
  • prefix (string): the prefix disguise to use. Currently only supported on stream connections.

Example:

server: example.com
server_port: 4321
method: chacha20-ietf-poly1305
password: SECRET
prefix: "POST "

LegacyShadowsocksURI

LegacyShadowsocksURI represents a Tunnel that uses Shadowsocks as the transport. It implements the legacy URL format for backwards-compatibility.

Format: string

See Legacy Shadowsocks URI Format and SIP002 URI scheme. We don't support plugins.

Example:

ss://chacha20-ietf-poly1305:SECRET@example.com:443?prefix=POST%20

ShadowsocksConfig

ShadowsocksConfig can represent a Stream or Packet Dialers, as well as a Packet Listener that uses Shadowsocks.

Format: struct

Fields:

  • endpoint (EndpointConfig): the Shadowsocks endpoint to connect to
  • cipher (string): the AEAD cipher to use
  • secret (string): used to generate the encryption key
  • prefix (string, optional): the prefix disguise to use. Currently only supported on stream connections.

Example:

endpoint: example.com:4321
cipher: chacha20-ietf-poly1305
secret: SECRET
prefix: "POST "

Meta Definitions

FirstSupportedConfig

Uses the first config that is supported by the application. This is a way to incorporate new configs while being backwards-compatible with old configs.

Format: struct

Fields:

Interface

Interfaces allow for choosing one of multiple implementations. It uses the $type field to specify the type that config represents.

Example:

$type: shadowsocks
endpoint: example.com:4321
cipher: chacha20-ietf-poly1305
secret: SECRET