socks.md

socks

← index · diagnosed problems

socks — an outbound, sing-box type socks. Also written as socks5, socks4, socks4a. 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	socks
singbox_type	socks
kind	outbound
aliases	socks5, socks4, socks4a
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
socks://…?…         ──▶ 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 — username:password of the account.
  • Type: username:password
  • Maps to: username, password
• 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.

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
• version — SOCKS protocol version.
  • Type: enum, "", 4, 4a, 5, normalized: trim_lower
  • Default: 5
  • If invalid: removed → type_invalid
• username — Account user name.
  • Type: string, role credential
  • Set by link parameter: userinfo
• password — Account password.
  • Type: string, secret
  • Set by link parameter: userinfo
• 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
• 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
• port_invalid
  • server_port — the value does not fit the field → node dropped
• type_invalid
  • version — the value does not fit the field → removed
  • network — the value does not fit the field → removed
  • udp_over_tcp.version — 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.

• version — normalized: trim_lower
• network — normalized: trim_lower
• tcp_keep_alive — normalized: duration_bare_seconds
• tcp_keep_alive_interval — normalized: duration_bare_seconds

Structural translations. Decisions taken while the link is being read, before any value is judged: whether a block exists at all, where a field comes from, or how one input becomes several fields. The sanitizer sees a finished body and cannot take them.

• the URI scheme itself: socks4:// / socks4a:// / socks:// / socks5:// → version = "4" / "4a" / "5" — A SOCKS link has no parameter for the protocol version in any dialect — the scheme carries it, the way the proxy-https:// suffix carries TLS.
  • Kind: structure

Degradation

The node is dropped

• server_port — invalid value
• server — invalid value

The field is removed, the node lives on

• inet4_bind_address — invalid value
• network — invalid value
• udp_over_tcp.version — invalid value
• version — invalid value