Motivation

When the server changes SS config(such as address, port, method, password), the client can auto-update config without user interaction.

Overview

1. server provides the URL of the online config file.
2. client fetch and save online config.
3. client periodically checks for config updates.

Basic file format

Basically, we follows the original JSON config format of shadowsocks. The required fields are:

{
  "server": "198.199.101.152",
  "server_port": 8388,
  "password": "u1rRWTssNv0p",
  "method": "aes-256-cfb",
  "remarks": "Example 1"
}

To support multiple servers, put those server objects into one JSON array.

Extended file format

The JSON config can be extended with any client specific field. Any unsupported filed can be just ignored.

{
  // config file struct version
  "version": 1,
  "remark": "Some server",
  "servers": [
    {
      // config id, so the client can detect it's a new server or just changed password
      "id": "1a2b3c4d",
      "remarks": "Server A",
      // SS connect config, same as shadowsocks-libev
      "server": "example.com",
      "server_port": 1234,
      "password": "example",
      "method": "chacha20-ietf-poly1305",
      "plugin": "xxx",
      "plugin_opts": "xxxxx"
    },
    // another server config
    {
      "id": "1a2b3c4e",
      "remarks": "Server B",
      "server": "example.com",
      "server_port": 4321,
      "password": "example",
      "method": "chacha20-ietf-poly1305",
      "plugin": "xxx",
      "plugin_opts": "xxxxx"
    }
  ]
}

Remark

1. The server SHOULD provide HTTPS to avoid MITM, and the client MUST NOT ignore cert error.
2. The config URL MAY include query params to identify a user as authentication.
3. The config URL MAY return HTTP redirects, the client SHOULD follow it at least once.
4. The client MAY check updates on App start/open/connected, SHOULD provide a button to force a refresh.
5. The server MAY omit some field in the config, except id, server, server_port, password, method in servers.

TODO

• Improvement this spec document.
• Implement in clients that have server manager feature(such as shadowsocks-windows, shadowsocks-android).