v2ray/v2ray-core

FOV001 - Endpoint Specification

VictoriaRaymond opened this issue · 8 comments

VictoriaRaymond commented

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 as 123e4567-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 network is ws or http, the path-info is 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.

  • http is effective only when network is tcp.
  • srtp, utp, wechat-video, dtls, wireguard are effective when network is mkcp or quic.

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).

tjLEIIQM3 commented

请教，匹配endpoint的正则怎么写？注意server-address可能是ipv6。
path和comment包含?@等特殊符号的奇葩情况先不考虑。

p.s.为什么要正侧：
私人之间分享不用考虑，直接要config.json。
公开的分享很多是在论坛或者4月份将关闭的Google+这些地方，所以每行一个\r\n不现实。
批量导入的时候就需要正则，或者每次导入时都开个记事本手动查找替换一番。

boypt commented

可加一个提醒，如果是IPv6地址，应强制使用[]括号 (如同 https://tools.ietf.org/html/rfc2732 对URL的标准)

避免与混淆导致解析困难。

xiaokangwang commented

We should build a standardized parser for this. If no one is on this task, I can have this done.

  • 👍5
eycorsican commented

kitsunebi-android has partial support (Protocol Oriented Serialization and Subscription) for this specification now.

  • 👍2
GeorgeGhost commented

Can anyone recomend any subscription server implemetation?

github-actions commented

This issue is stale because it has been open 120 days with no activity. Remove stale label or comment or this will be closed in 5 days

github-actions commented

This issue is stale because it has been open 120 days with no activity. Remove stale label or comment or this will be closed in 5 days

septs commented

MIME provides text/uri-list definition, I think text/uri-list definition can be used to replace text/plain.

see https://www.iana.org/assignments/media-types/text/uri-list
see https://www.rfc-editor.org/rfc/rfc2483#section-5