panel/node-plugins.md at af14e4f61a699c8fdee6367d2575a456feeac541

VPN/panel

Fork 0

mirror of https://github.com/remnawave/panel.git synced 2026-04-12 17:24:16 +00:00

Files

kastov af14e4f61a docs: expand node plugins documentation

2026-03-07 20:03:30 +03:00

17 KiB

Raw Blame History

sidebar_position, title

sidebar_position	title
99	Node Plugins β

Плагины – это дополнительные модули, которые можно активировать на Remnawave Node для дополнительных функций: Torrent Blocker, Blacklist, настройка Connection Drop.

:::warning

🚧 Эта страница находится в стадии разработки.

:::

:::tip

Плагины для нод доступны начиная с версии Remnawave Panel & Remnawave Node v2.7.0.

:::

Требования

Для корректной работы плагинов в обязательном порядке требуется добавить директиву cap_add: NET_ADMIN в конфигурацию Remnawave Node.

services:
    remnanode:
        container_name: remnanode
        hostname: remnanode
        image: remnawave/node:latest
        network_mode: host
        restart: always
        // highlight-next-line-green
        cap_add:
            // highlight-next-line-green
            - NET_ADMIN
        ulimits:
            nofile:
                soft: 1048576
                hard: 1048576
        environment:
            - NODE_PORT=<NODE_PORT>
            - SECRET_KEY=<SECRET_KEY>

Так же вы должны убедиться, что на хостовой машине доступен nftables. Впрочем, он уже установлен по умолчанию на большинстве дистрибутивов.

nft --version

:::danger

Отнеситесь к настройке плагинов с осторожностью, плагины Torrent Blocker и Blacklist будут работать напрямую с фаерволом на вашем сервере.

:::

Какую именно таблицу создаст Remnawave Node для работы плагинов?

table ip remnanode {
        set blacklist {
                type ipv4_addr
                flags timeout
        }

        set torrent-blocker {
                type ipv4_addr
                flags timeout
        }

        chain input {
                type filter hook input priority filter - 10; policy accept;
                ip saddr @blacklist log prefix "blacklist: " drop
                ip saddr @torrent-blocker log prefix "torrent-blocker: " drop
        }

        chain forward {
                type filter hook forward priority filter - 10; policy accept;
                ip saddr @blacklist log prefix "blacklist: " drop
                ip saddr @torrent-blocker log prefix "torrent-blocker: " drop
        }
}
table ip6 remnanode6 {
        set blacklist6 {
                type ipv6_addr
                flags timeout
        }

        set torrent-blocker6 {
                type ipv6_addr
                flags timeout
        }

        chain input {
                type filter hook input priority filter - 10; policy accept;
                ip6 saddr @blacklist6 log prefix "blacklist: " drop
                ip6 saddr @torrent-blocker6 log prefix "torrent-blocker: " drop
        }

        chain forward {
                type filter hook forward priority filter - 10; policy accept;
                ip6 saddr @blacklist6 log prefix "blacklist: " drop
                ip6 saddr @torrent-blocker6 log prefix "torrent-blocker: " drop
        }
}

Структура конфигурации

{
    "blacklist": {
        "ip": [],
        "enabled": false
    },
    "torrentBlocker": {
        "enabled": false,
        "ignoreLists": {
            "ip": [],
            "userId": []
        },
        "blockDuration": 3600
    },
    "connectionDrop": {
        "enabled": false,
        "whitelistIps": []
    },
    "sharedLists": []
}

:::tip

Редактор конфигурации плагинов поддерживает подсказки (наведитесь на объект, чтобы прочитать описание), а так же автокомплит.

:::

Torrent Blocker

:::danger

Для работы этого плагина необходима минимальная версия Xray-Core – ??.??.??. Эта версия ядра идет по умолчанию с Remnawave Node v2.7.0.

:::

Torrent Blocker – это плагин, который блокирует IP-адрес, с которого был обнаружен Torrent-трафик.

Конфигурация

"torrentBlocker": {
    "enabled": false,
    "ignoreLists": {
        "ip": [],
        "userId": []
    },
    "blockDuration": 3600
},

Field	Type	Description
`enabled`	boolean	Включает или выключает плагин, по умолчанию выключен
`ignoreLists`	object	Список IP-адресов и ID пользователей, которые будут игнорироваться плагином
`blockDuration`	number	Время блокировки в секундах

{
    "ip": [],
    "userId": []
}

Field	Type	Description
`ip`	array	Список IP-адресов, которые будут игнорироваться плагином. Можно использовать списки из конфигурации Shared Lists.
`userId`	array	Список ID пользователей, которые будут игнорироваться плагином

Техническая информация

Плагин использует одно из нововведений в Xray-Core – webhook (PR: #5722). Поэтому для работы плагина необходима версия Xray-Core ??.??.?? или выше.

Как включение плагина влияет на конфигурацию Xray-Core

Если этот плагин включен, Remnawave Node автоматически применит необходимые изменения в конфигурацию Xray-Core, с вашей стороны кроме включения плагина ничего делать не требуется.

:::warning

Как и написано выше – здесь описывается лишь то, что именно будет изменено в конфигурации Xray-Core. Не добавляйте эти изменения вручную, они будут применены автоматически.

:::

{
    "inbounds": [],
    "outbounds": [
        {
            "tag": "DIRECT",
            "protocol": "freedom"
        },
        {
            "tag": "BLOCK",
            "protocol": "blackhole"
        },
        // highlight-next-line-green
        {
            // highlight-next-line-green
            "tag": "RW_TB_OUTBOUND_BLOCK",
            // highlight-next-line-green
            "protocol": "blackhole"
            // highlight-next-line-green
        }
    ],
    "routing": {
        "rules": [
            // highlight-next-line-green
            {
                // highlight-next-line-green
                "protocol": [
                    // highlight-next-line-green
                    "bittorrent"
                    // highlight-next-line-green
                ],
                // highlight-next-line-green
                "outboundTag": "RW_TB_OUTBOUND_BLOCK",
                // highlight-next-line-green
                "webhook": {
                    // highlight-next-line-green
                    "url": "<REPLACED IN RUNTIME BY REMNAWAVE NODE>",
                    // highlight-next-line-green
                    "deduplication": 30
                    // highlight-next-line-green
                }
            }
        ]
    }
}

Правило всегда будет помещаться в начало массива rules, перед остальными правилами. А outbound будет всегда добавляться в конец массива outbounds.

Принцип работы

В рамках Xray-Core невозможно полностью блокировать Torrent-трафик. Xray-Core способен отслеживать только ~10-30% torrent-трафика, поэтому под "блокировкой" имеется в виду то, что после изначального обнаружения хотя бы одного пакета – IP-адрес, с которого пришел этот пакет, будет заблокирован на время, указанное в конфигурации.

После получения пакета, Xray-Core отправит информацию о нем в webhook, который будет обрабатываться Remnawave Node. После его получения – Remnawave Node моментально блокирует IP-адрес (в nftables), а так же обрывает соединение (аналог команды ss -k, conntrack -D).

Итак, принцип работы по пунктам можно описать вот так:

Remnawave Node добавляет необходимые изменения в конфигурацию Xray-Core.
Пользователь использует торрент
Его трафик попадает под правило, добавленное Remnawave Node в конфигурацию Xray-Core.
Xray-Core отправляет информацию о пакете в webhook.
Remnawave Node блокирует IP-адрес и обрывает соединение.
В течении ~15-30 секунд эта информация будет передана в Remnawave Panel.
Remnawave Panel отправит уведомление администратору в Telegram и так же отправит вебхук (torrent_blocker.report, scope: torrent_blocker).

:::info

Важно заметить, что дальнейшие действия относительно нарушителя вам необходимо реализовать самостоятельно. Remnawave Panel предоставляет все возможности для этого. После получения вебука от панели – вы можете перевести пользователя в статус DISABLED, если хотите чтобы пользователь не смог подключаться ко всем серверам.

:::

Что придет в вебхуке (`torrent_blocker.report`)

Вебхук будет содержать полный объект уже знакомых нам объектов node и user, а так же объект report, который содержит всю доступную информацию.

{
    "scope": "torrent_blocker",
    "event": "torrent_blocker.report",
    "timestamp": "2026-03-07T16:02:50.564Z",
    "data": {
        "node": {},
        "user": {},
        "report": {
            "actionReport": {
                "blocked": true,
                "ip": "<omitted>",
                "blockDuration": 60,
                "willUnblockAt": "2026-03-07T16:03:48.986Z",
                "userId": "2",
                "processedAt": "2026-03-07T16:02:48.986Z"
            },
            "xrayReport": {
                "email": "2",
                "level": 0,
                "protocol": "bittorrent",
                "network": "tcp",
                "source": "<omitted>:51431",
                "destination": "<omitted>:59755",
                "routeTarget": null,
                "originalTarget": "tcp:<omitted>:59755",
                "inboundTag": "VLESS_TCP_REALITY",
                "inboundName": "vless",
                "inboundLocal": "<omitted>:443",
                "outboundTag": "RW_TB_OUTBOUND_BLOCK",
                "ts": 1772899368
            }
        }
    }
}

Blacklist

Blacklist – это плагин, который перманентно блокирует IP-адрес, который находится в списке.

Конфигурация

"blacklist": {
    "ip": [],
    "enabled": false
}

Field	Type	Description
`enabled`	boolean	Включает или выключает плагин, по умолчанию выключен
`ip`	array	Список IP-адресов, которые будут заблокированы плагином. Можно использовать списки из конфигурации Shared Lists.

Принцип работы

IP-адреса, указанные в списке – будут заблокированы в nftables.

:::danger

Blacklist – это очень опасный инструмент. Будьте внимательны и осторжожны при составлении списков.

:::

Connection Drop

Connection Drop – это не полноценный плагин, а небольшая надстройка для того, чтобы была возможность добавлять IP-адреса в whitelist для функционала Connection Drop.

Начиная с версии Remnawave Node v2.6.0 – и при включении директивы cap_add: NET_ADMIN – Remnawave Node автоматически сбрасывает соединения при удалении пользователя из Xray-Core. В случае использования мостов – это могло привести к тому, что мостовое соединение могло быть разорвано в результате работы этой функции.

Начиная с версии Remnawave Node v2.7.0 – вы можете включить whitelist для функционала Connection Drop.

:::note

Функции Connection Drop будут работать всегда, здесь настраиваться только включения или выключения белого списка для этого функционала.

:::

Конфигурация

"connectionDrop": {
    "enabled": false,
    "whitelistIps": []
}

Field	Type	Description
`enabled`	boolean	Включает или выключает плагин, по умолчанию выключен
`whitelistIps`	array	Список IP-адресов, которые будут добавлены в whitelist для функционала Connection Drop.

Shared Lists

Shared Lists – это список IP-адресов, которые могут быть использованы в других плагинах.

Конфигурация

"sharedLists": [
    {
        "name": "ext:my-list",
        "type": "ipList",
        "items": ["127.0.0.1", "127.0.0.2"]
    }
]

Field	Type	Description
`name`	string	Имя списка, должно начинаться с `ext:`
`type`	string	Тип списка, должен быть `ipList`
`items`	array	Список IP-адресов

Пример использования в конфигурации Torrent Blocker:

"torrentBlocker": {
    "enabled": false,
    "ignoreLists": {
        "ip": ["ext:my-list"]
    },
    "blockDuration": 3600
}

17 KiB Raw Blame History Unescape Escape

Требования

Структура конфигурации

Torrent Blocker

Конфигурация

Техническая информация

Принцип работы

Blacklist

Конфигурация

Принцип работы

Connection Drop

Конфигурация

Shared Lists

Конфигурация

17 KiB

Raw Blame History