shadowsocks.md

shadowsocks

← index · diagnosed problems

ss — an outbound, sing-box type shadowsocks. Accepted from: share link, sing-box JSON, Xray JSON.

_{Schema checked against core 1.14.2-lx.11 · the link fragment (#…) is the node label}

Field	Value
scheme	ss
singbox_type	shadowsocks
kind	outbound
sources	uri, singbox, xray
Core the schema was checked against	1.14.2-lx.11
URI fragment	label

How to read this page

share link          mapper                node body              sanitizer            core config
shadowsocks://…?…   ──▶ link parameter   ──▶  sing-box JSON,    ──▶  checks each     ──▶  what sing-box
                     becomes a body         stored in state        body field's         is actually
                     field                                         value                started with

• Link parameters — the dictionary of the share link: every parameter this scheme understands, and the body field each one becomes.
• Body fields — the node body itself: the sing-box JSON kept in the launcher state. The rules here hold for every input alike — a share link, sing-box JSON, Xray JSON or a hand-filled form — because they are checked after the input has already become a body.
• Diagnosed problems — every warning code a node of this scheme can carry, and the field that raises it.
• Replacements — what is silently rewritten on the way in: other spellings of the same name, values normalized or substituted, and structural decisions the mapper takes before any value is judged.
• Degradation — the same rules grouped by outcome: what drops the node, what only drops a field, and what is merely worth knowing.

A bad value never breaks the whole config: the field is dropped, replaced or — at worst — the single node is. Each link parameter says which of the three happens to it, taken from the rule of the body field it maps to.

Link parameters

Everything a link of this scheme can carry. Maps to points at the body field the value lands in; If invalid is that field's own rule.

Common

• userinfo — base64 of method:password.
  • Type: base64(method:password)
  • Maps to: method, password
  • If invalid: node dropped → ss_method_invalid · Accepted with a notice for aes-128-ctr, aes-192-ctr, aes-256-ctr, aes-128-cfb, aes-192-cfb, aes-256-cfb, rc4-md5, chacha20-ietf, xchacha20 → ss_method_legacy
• host — The authority of the link: everything before : in scheme://…@host:port.
  • Maps to: server
  • If invalid: node dropped → field_missing
• port — The authority of the link: everything after : in scheme://…@host:port.
  • Maps to: server_port
  • If invalid: node dropped → port_invalid
• #fragment — The part after #: the name the node is shown under. It is not a body field — it is the node label.

Protocol-specific

• method — Encryption method.
  • Type: enum (other spellings of the same value are accepted): 2022-blake3-aes-128-gcm, 2022-blake3-aes-256-gcm, 2022-blake3-chacha20-poly1305, none, aes-128-gcm, aes-192-gcm, aes-256-gcm, chacha20-ietf-poly1305, xchacha20-ietf-poly1305 (allowlist ss_methods)
  • Maps to: method
  • If invalid: node dropped → ss_method_invalid · Accepted with a notice for aes-128-ctr, aes-192-ctr, aes-256-ctr, aes-128-cfb, aes-192-cfb, aes-256-cfb, rc4-md5, chacha20-ietf, xchacha20 → ss_method_legacy
• password — Account password.
  • Type: string
  • Maps to: password
• plugin — SIP003 plugin name.
  • Supported by LxBox only
  • Type: string · Default: ""
  • Maps to: plugin
• plugin_opts — SIP003 plugin options.
  • Supported by LxBox only
  • Type: string · Default: ""
  • Maps to: plugin_opts

Body fields

The node body itself — the sing-box JSON kept in the launcher state. The path is the one used in that body, and the rules below apply to every input alike: a share link, sing-box JSON, Xray JSON or a hand-filled form.

• server — Server address: domain or IP.
  • Type: string, format host
  • Required: the node is dropped without it
  • Set by link parameter: host
  • If invalid: node dropped → field_missing
• server_port — Server port.
  • Type: uint16, format port, 1–65535
  • Required: the node is dropped without it
  • Set by link parameter: port
  • If invalid: node dropped → port_invalid
• method — Encryption method.
  • Type: enum, none, aes-128-gcm, aes-192-gcm, aes-256-gcm, chacha20-ietf-poly1305, xchacha20-ietf-poly1305, 2022-blake3-aes-128-gcm, 2022-blake3-aes-256-gcm, 2022-blake3-chacha20-poly1305, aes-128-ctr, aes-192-ctr, aes-256-ctr, aes-128-cfb, aes-192-cfb, aes-256-cfb, rc4-md5, chacha20-ietf, xchacha20
  • Required: the node is dropped without it
  • Set by link parameter: userinfo, method
  • If invalid: node dropped → ss_method_invalid
  • Accepted with a notice for aes-128-ctr, aes-192-ctr, aes-256-ctr, aes-128-cfb, aes-192-cfb, aes-256-cfb, rc4-md5, chacha20-ietf, xchacha20 → ss_method_legacy
• password — Account password.
  • Type: string, secret, role credential
  • Required: the node is dropped without it
  • Set by link parameter: userinfo, password
• plugin — SIP003 plugin name.
  • Type: string
  • Set by link parameter: plugin
• plugin_opts — Options string passed to the plugin.
  • Type: string
  • Set by link parameter: plugin_opts
  • Meaningless without: plugin
• network — Networks this outbound handles.
  • Type: listable_string, tcp, udp, normalized: trim_lower
  • If invalid: removed → type_invalid
• udp_over_tcp — UDP-over-TCP settings.
  • Type: object
• udp_over_tcp.enabled — Tunnel UDP over the TCP connection.
  • Type: bool
  • Default: false
• udp_over_tcp.version — UDP-over-TCP protocol version.
  • Type: enum, 1, 2
  • Default: 2
  • If invalid: removed → type_invalid
• multiplex — Stream multiplexing settings.
  • Shared sub-schema, expanded below · reference page: _multiplex
• multiplex.enabled — Enable stream multiplexing.
  • Type: bool
  • Default: false
• multiplex.protocol — Multiplexing protocol.
  • Type: enum, "", h2mux, smux, yamux, normalized: trim_lower
  • Default: h2mux
  • If invalid: removed → type_invalid
• multiplex.max_connections — Maximum number of parallel connections.
  • Type: int, 0–…
  • Default: 0
  • If invalid: removed → type_invalid
• multiplex.min_streams — Minimum streams before opening a new connection.
  • Type: int, 0–…
  • Default: 0
  • If invalid: removed → type_invalid
• multiplex.max_streams — Maximum streams per connection.
  • Type: int, 0–…
  • Default: 0
  • If invalid: removed → type_invalid
• multiplex.padding — Pad multiplexed frames.
  • Type: bool
  • Default: false
• multiplex.brutal — TCP Brutal congestion control settings.
  • Type: object
• multiplex.brutal.enabled — Enable the TCP Brutal congestion control.
  • Type: bool
  • Default: false
• multiplex.brutal.up_mbps — Upload bandwidth in Mbps.
  • Type: int, 1–…
  • Required: the node is dropped without it
  • If invalid: removed → type_invalid
• multiplex.brutal.down_mbps — Download bandwidth in Mbps.
  • Type: int, 1–…
  • Required: the node is dropped without it
  • If invalid: removed → type_invalid
• detour — Tag of the outbound this connection is routed through.
  • Type: string, set by config build
• bind_interface — Network interface the connection is bound to.
  • Type: string
• inet4_bind_address — Local IPv4 address to bind to.
  • Type: string, format ipv4
  • If invalid: removed → type_invalid
• inet6_bind_address — Local IPv6 address to bind to.
  • Type: string
• connect_timeout — Timeout for establishing the connection.
  • Type: duration
• tcp_fast_open — Use TCP Fast Open.
  • Type: bool
  • Default: false
• disable_tcp_keep_alive — Disable TCP keepalive on this connection.
  • Type: bool
  • Default: false
• tcp_keep_alive — Idle time before the first TCP keepalive probe.
  • Type: duration, normalized: duration_bare_seconds
• tcp_keep_alive_interval — Interval between TCP keepalive probes.
  • Type: duration, normalized: duration_bare_seconds
• udp_fragment — Allow fragmenting UDP packets.
  • Type: bool, tristate
• domain_resolver — DNS server tag used to resolve the server domain.
  • Type: string
• network_strategy — Strategy for picking the outbound network interface. The core judges the value: the launcher passes it through unchecked.
  • Type: string
• network_type — Interface types allowed for this connection. The core judges the values.
  • Type: listable_string
• fallback_network_type — Interface types used when the primary ones are unavailable. The core judges the values.
  • Type: listable_string
• fallback_delay — Delay before falling back to the secondary network type.
  • Type: duration

Diagnosed problems

Every code that can be raised on a node of this scheme, including the ones coming from the shared TLS, transport, multiplex and dialer sub-schemas. Follow a code for what it means and what to do about it.

• field_missing
  • server — the value does not fit the field → node dropped
  • password — required and missing → node dropped
• field_requires
  • plugin_opts — set without plugin → removed
• port_invalid
  • server_port — the value does not fit the field → node dropped
• ss_method_invalid
  • method — the value does not fit the field → node dropped
• ss_method_legacy
  • method — the value is aes-128-ctr, aes-192-ctr, aes-256-ctr, aes-128-cfb, aes-192-cfb, aes-256-cfb, rc4-md5, chacha20-ietf, xchacha20 → kept with a notice
• type_invalid
  • network — the value does not fit the field → removed
  • udp_over_tcp.version — the value does not fit the field → removed
  • multiplex.protocol — the value does not fit the field → removed
  • multiplex.max_connections — the value does not fit the field → removed
  • multiplex.min_streams — the value does not fit the field → removed
  • multiplex.max_streams — the value does not fit the field → removed
  • multiplex.brutal.up_mbps — the value does not fit the field → removed
  • multiplex.brutal.down_mbps — the value does not fit the field → removed
  • inet4_bind_address — the value does not fit the field → removed

Replacements

Values. What the sanitizer does to a value before it reaches the node body.

• network — normalized: trim_lower
• multiplex.protocol — normalized: trim_lower
• tcp_keep_alive — normalized: duration_bare_seconds
• tcp_keep_alive_interval — normalized: duration_bare_seconds

Degradation

The node is dropped

• method — invalid value
• password — required and missing
• server_port — invalid value
• server — invalid value

The field is removed, the node lives on

• inet4_bind_address — invalid value
• multiplex.brutal.down_mbps — invalid value
• multiplex.brutal.up_mbps — invalid value
• multiplex.max_connections — invalid value
• multiplex.max_streams — invalid value
• multiplex.min_streams — invalid value
• multiplex.protocol — invalid value
• network — invalid value
• plugin_opts — conflicts with another field of the same node
• udp_over_tcp.version — invalid value

Kept as is, with a notice

• method — accepted, but worth knowing about