FOV001 - Endpoint Specification #1569
Description
Future of V (001): Endpoint Specification
Based on other requests (#1487), here is a proposal for V2Ray endpoint specification.
Endpoint
V2Ray endpoint is the entry point of a V2Ray service. It is usually provided by V2Ray service providers, and consumed by their users.
One endpoint should contain the following information:
- IP address, port (either TCP or UDP) and optionally domain name
- Transport protocol
- Proxy protocol
The endpoint can be serialized into two form: protocol oriented form, and service oriented form. The protocol oriented form is supposed to be used for one time exchange of an endpoint information. The service oriented form is supposed to be used for multiple endpoints together, and also regular updates afterwards.
Protocol Oriented Serialization
This form of serialization provides a single endpoint with specific proxy protocol.
<proxy-protocol> :// <user-info> @ <server-address> : <server-port> <path-info> ? <parameters> # <comment>
proxy-protocol: Name of the proxy protocol. Suggested names: ss for Shadowsocks, vmess1 for VMess. The name vmess is not used on purpose, to not conflict with existing serializations.
user-info: User infomation for connecting to the proxy. This information depends on spcified proxy being used. Suggestions:
- Shadowsocks:
user-info = websafe-base64-encode-utf8(method ":" password) - VMess:
user-info = uuid, such as123e4567-e89b-12d3-a456-426655440000
server-address: IP or domain address of the server.
server-port: Either a TCP port or UDP port number.
path-info: A valid HTTP path. It must begin with '/'.
parameters: List of additional parameters to describe the endpoint. The parameters are separated by '&'. Each parameter must be a valid HTTP query. See below for more details.
comment: Additional information regarding this serialization. It is not part of the actual endpoint.
Parameters
Below is a list of suggested parameters. All parameters are optional. If they are absent in the final URL, the default value shall be used.
For simplicity, all parameter names are lower-cased.
tag = <string>: Tag of the endpoint, when being used as an outbound in V2Ray. Default value is empty string.
tls = true | false: Whether or not to enable TLS. Default value is false.
network = tcp | mkcp | ws | http | quic: The network of the transport protocol. Default value is tcp.
- when
networkiswsorhttp, thepath-infois used as part of the protocol.
kcp.uplinkcapacity = <number>: Mapped to uplinkCapacity in mKCP configuration.
kcp.downlinkcapacity = <number>: Mapped to downlinkCapacity in mKCP configuration.
header = none | http | srtp | utp | wechat-video | dtls | wireguard: Obfuscation header for transport protocol. Default value is none.
httpis effective only whennetworkistcp.srtp,utp,wechat-video,dtls,wireguardare effective whennetworkismkcporquic.
mux = <number>: Concurrency of Mux. When the value is 0, Mux is disabled. Default value is 0.
Service Oriented Serialization
This form of serialization is transfering a list of endpoints and their routing rules.
v2ray://<provider-name> <path-info> ? <parameters> # <comment>
provider-name: Domain name from the service provider.
path-info: A valid HTTP path. It must begin with '/'.
parameters: List of additional parameters to describe the service. The parameters are separated by '&'. Each parameter must be a valid HTTP query. See below for more details.
comment: Additional information regarding this serialization. It is not part of the actual endpoint.
Parameters
Below is a list of suggested parameters. All parameters are optional. If they are absent in the final URL, the default value shall be used.
For simplicity, all parameter names are lower-cased.
encoding = base64: Encoding of outbound and rule parameter values. Default value is base64.
outbound = <string>: Mapped to one OutboundObject. When outbound appears multiple times in one serialization, each outbound represents a separate OutboundObject. This parameter must exist at least once, when subscription is off.
rule = <string>: Mapped to one RuleObject. Default value is empty string.
subscription = off | on: Default value is off.
Subscription
When subscription is on, the service provider must offer a HTTPS resource for updates of the V2Ray endpoint. The URL of HTTPS resource is converted from the service oriented serialization, by simply changing v2ray to https. For example, given the V2Ray endpoint:
v2ray://example-service.com/get-updates/?subscription=on
Users can assume the HTTPS resource available as:
https://example-service.com/get-updates/
This HTTPS resource outputs updated list of V2Ray endpoints in various of formats.
Simple List
The HTTPS resource must respond with HTTP header Content-Type: text/plain. The body of HTTP response is a list of V2Ray endpoints, separated by new line charaters (\r\n).