XRAY-JSON Subscription | Proposal

[iambabyninja]

Xray-JSON Subscription

Dear members of our large community!
I invite you to an open discussion regarding the Xray-JSON Subscription.

0. Abstract

Significant time has passed since the introduction of the V2ray-link standard for distributing configurations. With the global adoption of xray-core, there is a need for a more flexible and convenient way to distribute configurations for connecting to proxy services.

The growing popularity of XTLS has led to an increase in the number of sellers and, consequently, their clients. Unfortunately, the technical expertise of these clients varies greatly, requiring more attention to certain configuration parameters to ensure the security of the proxy server.

In particular, we are talking about providing routing, DNS, and other settings. Currently, each client-side proxy application defines its own way of providing additional instructions and parameters, which negatively impacts the overall user experience.

This document proposes to structure and generalize existing solutions to this problem into an agreement for representing subscriptions in JSON format.

We will cover the key principles, requirements, and usage examples of this configuration distribution format, and define the behavior of client-side proxy applications when encountering this method of configuration distribution.

1. Agreement

First, we need to define the basic rules, without which further agreement is invalid.

1.1 Use of HTTPS

The client application can only process this type of subscription if it was received over an encrypted channel. If the proxy client receives such content in plain text, it must return an error.

1.2 Case Sensitivity

All parameter names and string literals within the subscription content must be case-sensitive.

2. Overview

2.1 General Representation

In this agreement, we define a subscription (or group) as an array of connections in text form, where each element of the array is a fully valid JSON configuration based on the xray-core documentation, with the inclusion of several additional fields in each array element.

The general appearance of the subscription (group) provided to the proxy client should be as follows:

[
    {/* Configuration 1 */},
    {/* Configuration 2 */},
    {/* Configuration 3 */}
]

Note:
Core settings passed in the JSON configuration have higher priority than settings defined in the proxy application.

EXAMPLE

[
    {
        "remarks": "CONNECT_1" ,
        "dns": {},
        "routing": {},
        "inbounds": [],
        "outbounds": [],
        // ... (Other configuration parameters) 
    },
    {
        "remarks": "CONNECT_2" ,
        "dns": {},
        "routing": {},
        "inbounds": [],
        "outbounds": [],
        // ... (Other configuration parameters) 
    }	
]

2.2 Connection

As we defined earlier, this array includes at least one or more elements. In our agreement, each individual element is a separate, isolated connection. Each element (connection) must comply with the requirements set forth in the xray-core documentation.

EXAMPLE

{
    "remarks":"Connect1",
    "routing": {
        "rules": [
            {
                "ip": [
                    "geoip:cn"
                ],
                "outboundTag": "direct"
            }
        ]
    },
    "inbounds": [
        {
            "listen": "127.0.0.1",
            "port": 10808,
            "protocol": "socks"
        },
        {
            "listen": "127.0.0.1",
            "port": 10809,
            "protocol": "http"
        }
    ],
    "outbounds": [
        {
            "protocol": "vless",
            "settings": {
                "vnext": [
                    {
                        "address": "",
                        "port": 443,
                        "users": [
                            {
                                "id": "name", 
                                "encryption": "none",
                                "flow": "xtls-rprx-vision"
                            }
                        ]
                    }
                ]
            },
            "streamSettings": {
                "network": "tcp",
                "security": "reality",
                "realitySettings": {
                    "fingerprint": "chrome",
                    "serverName": "www.lovelive-anime.jp", 
                    "publicKey": "Z84J2IelR9ch3k8VtlVhhs5ycBUlXA7wHBWcBrjqnAw", 
                    "shortId": "6ba85179e30d4fc2" 
                }
            },
            "tag": "proxy"
        },
        {
            "protocol": "freedom",
            "tag": "direct"
        }
    ]
}

2.2.1 REMARK Field

To improve user experience, each element of the configuration array can contain a remark field:

remark: string
Connection name

Note:
If this parameter is present, the proxy client must set the corresponding connection name in the GUI.

Note:
If this parameter is absent or its value is declared as NULL, the client is free to set the connection name at its own discretion.

3. Meta-information

Along with the configuration file itself, the client can receive the following headers to represent additional meta-information:

3.1 profile-title

profile-title: string
Profile name in base64 UTF8 encoding

Example:

profile-title: base64:0YXRg9C5

Note:
If this header is present, the client should set this value as the name of the subscription/group in the GUI.

Note:
If the value of this header is NULL, the client can set the name of the subscription/group at its own discretion.

3.2 profile-update-interval

profile-update-interval: int
Automatic configuration file update interval in hours

Example:

profile-update-interval: 1

Note:
If this header is present, the client should set this automatic update interval for the subscription.

Note:
If the header is absent, the client is free to set the value at its own discretion.

3.3 subscription-userinfo

Information about the traffic and expiration date of the group

Example:

subscription-userinfo: upload=0; download=4460105213; total=2147483648; expire=1710442799

3.4 profile-web-page-url

Header containing the subscription link

Example:

profile-web-page-url: https://example.com/sub

[RPRX]

直接订阅 JSON，我觉得可以有，三年前有过这想法然后随着 X-flutter 一起没了，可以重启配套客户端项目，今年收捐款了所以 GPL 开源

现在 Xray 配置最大的问题就是出站写法过于复杂，@mmmray 开个 PR 把层层包裹去掉吧，三年前差点和 v2fly 一起推进但我人没了

[RPRX]

But on the other hand, functionality like connection splitting (across multiple CDN) is still on my personal agenda, and it would require some way to define multiple addresses as well.

这个可以用新配置格式来实现，而且这个应该和“id”平级，而目前唯一的“address”处于上一级，所以还是应该先拉平

[RPRX]

而且这个应该和“id”平级

或者写在 SplitHTTP 配置里，话说我突然觉得 address 和 port 都应该写在底层传输方式那里，@mmmray 你觉得呢

[RPRX]

话说我突然觉得 address 和 port 都应该写在底层传输方式那里

或者如果和 inbound 相对应的话，改为同样与“tag”平级

[mmmray]

here's the most extreme version i know

"layers": [
    {"type": "vless", "users": ...},
    {"type": "ws", "path": "..."},
    {"type": "tls", "serverName": ..., "alpn": "http/1.1"},
    {"type": "tcp", "address": "...", "fragment": ...}
]

this is how waterwall does it

also, mux would just be another layer as well, and possibly HTTP dialer too.

address only valid for tcp layer. other layers have no knowledge of address. serverName is now mandatory. I have no clue how TLS NextProto will work, probably alpn is mandatory for websocket as well. it's inconvenient but maximally flexible. anyway, it needs to be thought through more, because layers cannot be combined in arbitrary ways (even though the config format suggests it), for example it's not permissible to put UDP layer on top of WS.

[RPRX]

看得我都想步子迈大些扯到蛋了，之前更炸裂的想法是 NEXT-core 但 XTLS 不好弄了且被别人抢先做了且套娃会有内层流量特征问题

[khodedawsh]

Is V2rayNG not doing this already?
and what happens to backward compatibility? in case a newly added feature is used in the configuration, it might not get parsed and xray-core exits.
also what's the solution in case a client has support for other cores, and the server tries to send subscription payload, containing other configurations not supported by xray.
I understand one could just implement that into some client, to parse sharelinks too; but doesn't that break this standard? so a subscription payload valid to one client is not valid to another.

[iambabyninja]

no, but shouldn't matter. take hysteria2 for example

But the discussion is specifically about the subscription for xray-core, and xray-core does not support HY2.

I haven’t looked at your code in a while. How do you implement the delivery of this configuration in the subscription?

[khodedawsh]

我觉得这并不是一个问题，这是 Xray 的 JSON 订阅，当然只支持 Xray 所支持的协议

well true, but why not create a more generic solution to this while we're at it

[khodedawsh]

implemented built-in in Xray-core

btw i don't see much benefit in this

[mmmray]

Maybe it can be specified how parsing errors should be handled: If one config fails to parse, it should not affect other configs. This increases the chances that one subscription can be used for many cores, and seems like a good idea for other reasons. But there's still no guarantee that other cores will care about xray's subscription format at all, we can only hope they get inspired by it.

[khodedawsh]

we can only hope they get inspired by it.

yeah sure, inspired by the ability to directly push configs to turn a user into a reverse proxy

[Fangliding]

我觉得只需要一个出站就够了 DNS怎么填路由怎么填客户端作者更清楚 有的东西由远端下放总感觉有点奇怪 也有先例比如clash发放的配置入站监听0000导致有的人端口可以被扫到
现行的分享链接确实有缺陷 就是扩展性不佳 每次都要规定字段 不利于一些新功能 直接存整个出站config可能会好一些
还有一些为机场服务的部分 比如流量和过期 核心一直没添加商用有关的功能（比如限速和限连接数 快听的耳朵发麻了） 这牵头加上感觉有点表里不一了
有完整config配置需求的一个很大的原因其实是因为freedom的fragment和noise之类的功能 想用必须完整配置套娃dialerproxy 我觉得奇怪很久了 这一部分如果修改直接在单个入站的streamsetting生效会更好

[APT-ZERO]

Isn't 'Proposal' supposed to be something new?
you just copy-pasted accepted headers of Clash clients and v2rayNG's multi custom config body

[iambabyninja]

Did you read the text carefully?
I don’t think so.
Because if you had read it, you would have seen:

‘Currently, each client-side proxy application defines its own way of providing additional instructions and parameters, which negatively impacts the overall user experience.’

This document proposes to structure and generalize existing solutions to this problem into an agreement for representing subscriptions in JSON format.

I will repeat once again: the purpose of this document is to bring all existing solutions to a unified format, so that the behavior is consistent across different clients.

But the main goal is to introduce these solutions to other clients as well.

[cyc0der]

you have to mind that using whole JSON configuration as a subscription has some security flaws, for instance you can set reverse proxy or any unintentionally configuration on the client device

I've tested reverse proxy on v2rayNG and it works... easily possible to use the internet of user for any purpose

[RPRX]

可以限制一些功能，比如 reverse proxy

[khodedawsh]

doesn't that lead to double standards?

[RPRX]

doesn't that lead to double standards?

如果我没理解错的话你在阴阳怪气，我正式警告你这里讨论的是如何更好地实施 Xray JSON 订阅标准而不是要不要有它，以及这是 Xray-core 的 JSON、只适用于基于 Xray-core 的客户端、不会也没必要考虑其它 core，再发表令人不适的言论就 ban 了。

如果服务提供者只提供了 Xray JSON 订阅，那么你应当转向使用基于 Xray-core 的客户端，Clash 做订阅时也没考虑其它 core。

[RPRX]

而且这东西主要是给分享链接暂时没有的功能开了个口子，比如 fragment、noise 等，别的 core 也没有啊，不知道这人在想啥。

[khodedawsh]

如果我没理解错的话你在阴阳怪气，我正式警告你这里讨论的是如何更好地实施 Xray JSON 订阅标准而不是要不要有它，以及这是 Xray-core 的 JSON、只适用于基于 Xray-core 的客户端、不会也没必要考虑其它 core，再发表令人不适的言论就 ban 了。

I guess I don't have anything to say in that regard and will stop commenting in case it's making you uncomfortable.

而且这东西主要是给分享链接暂时没有的功能开了个口子，比如 fragment、noise 等，别的 core 也没有啊，不知道这人在想啥。

well I think the door is already open. this discussion could make it(Xray JSON) a better door however i mentioned my view about that too; it's already good enough.