XHTTP Setup

Standalone-мастер для схемы:

клиент -- VLESS Encryption + XHTTP packet-up + TLS :443 --> сайт frontend
Apache frontend -- HTTP/XHTTP --> зарубежный bare Xray exit :8083 --> интернет

На shared-hosting не устанавливаются Xray, Docker или фоновые сервисы. TLS завершается на существующем сайте, а Xray работает отдельным непривилегированным systemd-сервисом только на зарубежном exit.

Текущий исходный код имеет версию 0.6.6. До успешной публикации immutable Release v0.6.6 текущими публичными артефактами остаются файлы v0.6.5. Release v0.6.1 ошибочно отклоняет штатный ответ UFW (None), а v0.6.2 — нетронутый package seed UFW 0.36.x без ### END RULES ###. v0.6.3 исправляет seed, но отклоняет штатные ownership notices Ubuntu от nft и может неверно описать rollback первого UFW-запуска. v0.6.4 исправляет эти два ложных отказа. v0.6.5 до любого нового изменения fresh exit повторяет рабочую локальную проверку Apache: на одном secret URL отдельные временные правила дают обязательный 302, затем наблюдение буквального [P,L] на 127.0.0.1:9; 502/503/504 считается сильным положительным сигналом, а иной bounded outcome не подменяет решающую TCP-пробу. Исходные bytes .htaccess восстанавливаются после каждой транзакции. Затем три независимые волны проверяют непосредственно будущий backend TCP/8083 вместо случайных высоких портов. 0.6.6 дополнительно принимает обе подтверждённые семьи ISPmanager-узлов REG.RU: vipNNN.hosting.reg.ru и serverNNN.hosting.reg.ru.

Быстрый запуск на Windows

Один раз установите WSL2 с Ubuntu или Debian. Для Ubuntu:
```
wsl --install -d Ubuntu
```
Если Windows попросит перезагрузку, перезагрузитесь и один раз откройте Ubuntu. Дальше вручную ставить Linux-пакеты не нужно: launcher проверит и при необходимости установит их сам.
В ISPmanager заранее вручную создайте сайт и настройте DNS/TLS по короткому списку. Мастер сайт не создаёт.
После успешной публикации Release v0.6.6 возьмите xhttp-setup-0.6.6-windows-wsl.zip и его .sha256 с одной страницы этого Release. Не подменяйте их файлами другой версии. Выберите в Проводнике «Извлечь все» и дважды нажмите START-WINDOWS.cmd.
Отвечайте на вопросы по одному. 0.6.6 предложит прямое подключение к REG.RU или необязательный SSH-мост. Никакие SHA-256, host-key fingerprint, UUID, XHTTP path, egress-IP, UFW-команды или APPLY PC вводить не нужно.
Не закрывайте окно до сообщения об успешной сквозной проверке. Только после неё мастер создаст client.vless и покажет клиентскую ссылку.

Полная инструкция для скачанного Windows ZIP находится в windows/INSTRUCTION.txt. В release она публикуется как самостоятельный файл с подставленной версией.

Что нужно ввести

В 0.6.6 PC-мастер спрашивает:

IPv4 выходного сервера;
SSH port выхода, обычно 22;
SSH login выхода, нужен прямой root;
SSH password выхода — скрытый ввод;
Использовать мост для входа? [y/N].

Ответ N или пустой Enter оставляет прямой доступ с домашнего ПК/WSL. При ответе Y дополнительно запрашиваются IPv4 моста, SSH login моста ([root]) и скрытый SSH password. Порт моста фиксирован как 22 и отдельно не спрашивается. После выбора маршрута мастер продолжает спрашивать:

точный HTTPS-адрес панели REG.RU/ISPmanager, включая порт, например https://vip123.hosting.reg.ru:1500/ или https://server205.hosting.reg.ru:1500/;
основной логин REG.RU;
пароль панели REG.RU — скрытый ввод;
IPv4 подключения REG.RU из карточки/данных подключения сайта;
домен frontend.

Пароль панели сначала проверяется для SFTP основного аккаунта. Только если SFTP вернул именно ошибку аутентификации, мастер дополнительно и скрыто спросит отдельный SFTP-пароль: для REG.RU это пароль из раздела письма «Доступ к FTP» основного аккаунта. Его не вводят заранее; MySQL login/password/host не нужны. Всего допускается не более трёх попыток. При сетевой ошибке, неверном document root или другой ошибке мастер не перебирает пароли.

Что PC-мастер делает автоматически

принимает первые SSH-ключи exit, необязательного моста и SFTP frontend по TOFU и сохраняет их для конкретных endpoint; при повторном запуске безопасно читает локальную запись без нового ssh-keyscan, а немедленное реальное SSH/SFTP-соединение с StrictHostKeyChecking=yes блокирует исчезновение или смену закреплённого ключа;
проверяет root SSH и существующий сайт read-only запросом ISPmanager; сайт и его настройки через API не создаёт и не меняет;
проверяет ровно одну A-запись домена, отсутствие AAAA, точные SNI и IPv4 подключения;
использует обычную проверку публичного CA, а при её отказе автоматически закрепляет SHA-256 стабильного точного leaf-сертификата (обычно self-signed); allowInsecure не создаётся;
сначала проверяет сайт, DNS, SFTP и TLS без изменений на exit, создаёт случайный XHTTP path и выполняет две полностью откатываемые локальные canary;
готовит чистый Debian 12+/Ubuntu 22.04+ exit: ставит только разрешённый набор пакетов, безопасно подготавливает UFW и сохраняет SSH-доступ;
измеряет фактические egress IPv4 exit и Apache REG.RU тремя отдельными волнами непосредственно через будущий backend TCP/8083; каждая волна использует новый nonce и не менее трёх независимых SYN, а UUID создаётся только после совпадения всех трёх проб;
применяет на exit точную пару UFW: allow backend только от измеренного frontend IPv4 /32, затем deny для остальных;
транзакционно добавляет только managed-блок .htaccess, не перезаписывая чужие правила и не трогая главную страницу сайта;
запускает временный локальный Xray-клиент, проверяет SOCKS-трафик через frontend и требует совпадения внешнего IP с egress-IP exit;
выдаёт VLESS URI только после успешного E2E.

Мастер не создаёт сайт, не выпускает домен, не настраивает DNS-провайдера и не копирует, не маскирует и не reverse-proxy'ит RuFox или любой другой сайт. index.html и содержимое главной страницы остаются без изменений (placeholder_mode=keep).

Необязательный SSH-мост в текущем PC-мастере

Мост нужен только когда контроллер не может надёжно обратиться к REG.RU напрямую. Мастер принимает первый ключ моста по TOFU, открывает один SSH-сеанс на TCP/22 и требует, чтобы введённый пользователь фактически имел UID 0. Мост должен быть доверенным Linux-узлом с разрешённым SSH TCP forwarding.

При выборе моста через его локальные loopback-forward идут только setup-запросы к frontend:

HTTPS к ISPmanager;
SFTP, включая first-use ssh-keyscan, обе локальные control-транзакции и последующие транзакции .htaccess;
TLS/SNI-проверка frontend, обе локальные HTTPS-canary, три волны TCP/8083 и финальный E2E.

SSH к exit во всех случаях остаётся прямым с контроллера, а DNS A/AAAA проверяется локально, не через мост. На мост не устанавливается Xray, он не попадает в client.vless или VLESS URI и не участвует в рабочем datapath после настройки. SSH-сеанс моста закрывается при завершении или ошибке мастера.

SFTP-команды не создают новый password-login для каждого ls/get/put. Мастер держит один приватный ControlMaster на ограниченную логическую транзакцию: проверку document root, отдельные 302-контроль и локальную [P]-canary .htaccess, каждую из трёх [P]-проб на TCP/8083 и финальное применение. Дочерний sftp -b не может переподключиться напрямую при потере этого master. После сомнительной записи мастер не повторяет команду. Только чистая транспортная ошибка во время rollback разрешает один новый закреплённый сеанс для сверки уже созданного журнала; конфликт файлов или недоказанный откат останавливает запуск.

Прямые SSH-проверки exit также не создают новый password-login для каждой команды. PC-мастер использует отдельные приватные закреплённые сеансы для первичной проверки доступа, подготовки сервера и применения exit. Дочерние команды не имеют прямого или credential fallback. После изменений UFW мастер обязательно проверяет UID 0 через новое независимое SSH-соединение, пока предыдущий сеанс остаётся доступен для разрешённого rollback. Потерянную или неопределённо завершившуюся команду он не повторяет автоматически.

Требования перед запуском

Существующий frontend

сайт уже создан вручную в ISPmanager;
домен имеет ровно одну A-запись, без AAAA/CNAME для этого имени и без CDN/proxy; DNS A и введённый client-connect IPv4 проверяются как разные роли;
TLS-vhost сайта работает на 443;
HSTS и принудительный HTTP → HTTPS redirect выключены на время настройки;
PHP работает в режиме FastCGI (Apache), чтобы запрос неизвестного XHTTP path доходил до Apache и .htaccess;
основной аккаунт имеет SFTP-доступ к фактическому document root сайта;
Apache разрешает mod_rewrite, mod_proxy, mod_proxy_http и флаг [P].

FastCGI (Apache) доказывает только то, что неизвестный URL доходит до Apache и .htaccess. Он не доказывает, что конкретный тариф/узел разрешает reverse proxy через [P]. Это серверная возможность провайдера: пользователь shared- аккаунта не может установить недостающие модули. Не включайте ради неё CGI, Python или ProxyRequests On: они не заменяют mod_proxy_http, а ProxyRequests On может превратить vhost в опасный forward proxy.

Мастер сам получает точный document root из уже существующей записи сайта в ISPmanager. Совпадение домена должно быть единственным; неоднозначный ответ панели отклоняется.

Чистый exit

Debian 12+ или Ubuntu 22.04+ с systemd;
стабильный публичный IPv4 и прямой root SSH по паролю;
свободный TCP/8083;
нет Docker/containerd, чужого Xray, отдельного активного/enabled nftables.service, custom nftables/iptables и нестандартной сохранённой конфигурации UFW.

Необязательный мост

отдельный доверенный Linux-узел с публичным IPv4;
SSH на TCP/22 по паролю;
вход введённого пользователя сразу даёт UID 0 (по умолчанию root);
сервер разрешает локальные TCP-forward к ISPmanager, SFTP и frontend:443.

При свежей подготовке active UFW принимается только с точным SSH guard текущего порта, созданным этим сценарием. При доказанном resume допустимы этот guard и полная точная managed-пара backend: allow от сохранённого frontend /32, затем deny остальным. Мастер сверяет весь пользовательский UFW inventory; пустой active UFW, другой порт, частичная пара, дубликат и любое постороннее правило отклоняются. Если UFW ещё не активен, мастер автоматически создаёт SSH allow, включает временный systemd rollback guard, включает UFW и подтверждает вход новой SSH-сессией. Аварийный guard только отключает UFW и никогда не удаляет SSH allow: после успешного disable спящее точное правило безопасно сверяется и удаляется следующим запуском. При неоднозначном состоянии мастер останавливается, а не пытается объединить чужой firewall.

Автоматический путь рассчитан на чистый VPS без параллельного root-оператора или второго установщика. Не меняйте UFW/nftables/iptables вручную во время запуска. Для pristine/inactive UFW 0.36.x принимаются только две целые формы user.rules/user6.rules: нетронутый seed, byte-for-byte совпадающий с проверенным dpkg локальным package template, либо один из полных штатных пустых rewritten-layouts для пяти logging levels и обоих вариантов rate-limit chains. Любое постороннее или неполное содержимое внутри или вне RULES section отклоняется. После аварии первого enable официальный переход package seed в полный пустой rewritten-layout и inert ACCEPT-policy UFW scaffold считается восстановлением только после повторной строгой проверки persistent и kernel-состояния. Сообщение об ошибке отдельно отражает фактическое состояние rollback guard. Проверка persistent UFW rules строгая, но имена системных ufw-* chains сами по себе не являются криптографическим доказательством их происхождения: заранее изменённые raw-файлы before/after или содержимое внутренних chains требуют ручной проверки либо нового чистого VPS. В фиксированных человекочитаемых labels/headers вывода команд мастер игнорирует только регистр, пробелы и оформительную пунктуацию. Избыточные или пропущенные слова, machine fields, пути, rules, keys, identifiers и comments остаются exact и при неоднозначности дают STOP. Штатные nft ownership notices от iptables-nft допускаются только как полный набор для точных ip filter/ip6 filter tables, уже принятых строгим ruleset- validator. Пунктуация, пробелы и регистр сообщения несущественны; пропуск, дубликат, другая table или смешанная диагностика дают STOP.

Провайдерский cloud firewall/security group находится вне VPS и не управляется по SSH. Проба и финальный dataplane используют один и тот же TCP/8083. Если внешний firewall блокирует probe, временно разрешите входящий TCP/8083 и снова запустите мастер с теми же данными. После совпадения трёх проб мастер печатает точный Apache egress /32 и останавливается на интерактивном checkpoint. До нажатия Enter ограничьте TCP/8083 только напечатанным /32; если отдельного cloud firewall нет, ничего не меняйте и просто нажмите Enter. Без API конкретного провайдера этот ручной checkpoint универсально убрать невозможно.

Если все HTTPS-запросы TCP/8083-пробы получили 404, а exit не увидел ни одного SYN, не делайте вывод «cloud firewall заблокировал порт». К этому моменту точный локальный 302 уже прошёл. Если буквальный [P,L] на 127.0.0.1:9 дал 502/503/504, локальная proxy-обработка Apache также подтверждена; иной bounded outcome оставляет её неподтверждённой. В обоих случаях остаются неподтверждёнными доступ к конкретному TCP/8083, provider egress policy и внешний firewall/маршрут. Не открывайте диапазон портов, не включайте CGI, Python или ProxyRequests On; передавайте поддержке только redacted status/capture без secret path, UUID, паролей и клиентской ссылки.

TOFU: точный компромисс

Ручной SHA/fingerprint больше не нужен. При первом соединении мастер получает SSH-ключ exit, необязательного моста и SFTP-узла через ssh-keyscan и атомарно сохраняет точную приватную запись для каждого endpoint. При следующих запусках он проверяет эту локальную запись и не зависит от повторного ssh-keyscan. Сразу после этого выполняется настоящее SSH/SFTP-соединение только с StrictHostKeyChecking=yes; исчезновение или смена закреплённого ключа блокирует соединение до аутентификации и до удалённых изменений.

Это сохраняет шифрование и защиту от незаметной подмены после первого успешного контакта, но не подтверждает первый ключ через независимый канал. Активная MITM-атака именно при первом запуске может закрепить чужой ключ. Если такая модель угроз важна, независимо сверьте fingerprint у провайдера и используйте расширенный ручной режим. Доверие пользователя своему персональному компьютеру этого риска в сети не устраняет.

Для leaf, не прошедшего публичную CA+hostname проверку, действует аналогичный first-contact pin: мастер выполняет две независимые TLS-сессии, требует одинаковый DER, сохраняет его SHA-256 и блокирует смену leaf. В этом режиме срок, CA и hostname уже не проверяются; exact pin не доказывает сам по себе правильность Apache vhost. Переход на сертификат публичного CA допускается только после обычной проверки системным trust store и hostname; публичный сертификат может штатно обновляться.

Повторный запуск и восстановление

Состояние PC-установки хранится отдельно для домена с закрытыми правами. Пароли в него не записываются. Фазы preparing, exit_applying, exit_ready и complete позволяют после сбоя проверить существующий managed exit и безопасно продолжить с теми же UUID и XHTTP path. Изменившийся egress-IP не принимается автоматически.

Во время временного probe и финального frontend apply мастер использует транзакцию и rollback. Если процесс был жёстко прерван в фазе front_probe_in_progress или front_in_progress, следующий запуск останавливается fail-closed: сначала нужно сопоставить сохранённые backups с текущим .htaccess. Не удаляйте каталог состояния и не запускайте второй экземпляр параллельно.

Если frontend/E2E не завершён, exit может уже быть установлен и защищён UFW, но client.vless не выдаётся.

Сообщение SFTP SSH-транспорт не установился означает сетевой/маршрутный сбой, а не отказ пароля; отдельный пароль при нём не спрашивается. При выбранном мосте OpenSSH иногда печатает Connection to UNKNOWN port 65535: это служебное имя stdio ProxyCommand, а логической целью остаётся SFTP-host из URL панели на TCP/22. Не открывайте порт 65535 и не удаляйте TOFU-state. Подождите cooldown провайдера (если он неизвестен, 15–30 минут — только осторожная эвристика) и сделайте один повтор. Повторный timeout требует остановки и проверки доступности точного SFTP-host:22 с адреса моста/контроллера у хостинга; циклические запуски и перебор паролей запрещены.

Сообщение SSH-транспорт оборвался для exit также не доказывает неверный пароль. Мастер показывает только ограниченную и очищенную диагностическую категорию OpenSSH, не повторяет оборвавшуюся команду и сохраняет recovery-фазу. Если следующий запуск снова останавливается на том же прямом SSH-соединении, не запускайте его циклом: проверьте доступность SSH у VPS-провайдера, состояние sshd/cloud firewall и возможный rate limit. Закреплённый known_hosts для «повтора» не удаляйте; host-key mismatch требует независимой проверки ключа.

exact_recovery=failed, exact_reconciliation=required после неудачной recovery-сессии или текст rollback неполон означают немедленный STOP, а не обычный повтор. Сначала вручную сверьте точные managed UFW comments, состояние временного каталога и phase marker. Один повтор допустим только когда exact recovery уже подтверждён как succeeded либо сбой произошёл до любой мутации.

Запуск на Linux

Поддерживаемый контроллер — Debian 12+/Ubuntu 22.04+ с Python 3.10+. После успешной публикации Release v0.6.6 скачайте .pyz и .pyz.sha256 этой версии, проверьте checksum и запустите:

(
  set -Eeuo pipefail
  HASH="$(tr -d '\r\n' < xhttp-setup-0.6.6.pyz.sha256)"
  test "${#HASH}" -eq 64
  printf '%s  xhttp-setup-0.6.6.pyz\n' "$HASH" | sha256sum -c -
  python3 xhttp-setup-0.6.6.pyz --version
  exec python3 xhttp-setup-0.6.6.pyz pc
)

Из исходников:

python3 -m xhttp_setup pc

Расширенные режимы

pc — основной и единственный минимальный сценарий для обычного пользователя. Команды exit, front, full и doctor сохранены для диагностики, раздельного применения и ручной эксплуатации. Они намеренно могут требовать handoff, fingerprint, firewall acknowledgement и точное подтверждение apply. Не переносите их вопросы в PC-инструкцию.

Архивный ручной advanced-runbook v0.4.x сохранён в docs/reg-ru-pinned-tls.txt. Он описывает другой legacy-workflow и не должен смешиваться с автоматическим PC-мастером.

Безопасность изменений frontend

Frontend меняется через SFTP-транзакцию:

чужие строки .htaccess сохраняются, меняется только managed-блок;
непосредственно перед переключением повторно сверяется исходный файл;
при E2E-ошибке свои изменения откатываются к pre-apply снимкам;
конкурентная чужая правка не перезаписывается;
backups имеют случайные имена, локальные каталоги и секретные артефакты — закрытые права;
index.html и остальные файлы сайта не меняются.

Подробная модель угроз и восстановление описаны в SECURITY.md.

Файлы на exit и локальном компьютере

/opt/xhttp-setup/xray/v26.3.27/       закреплённый Xray и manifest
/etc/xhttp-setup/xray.json            managed-конфиг, 0640
/etc/systemd/system/xhttp-setup-xray.service
/var/lib/xhttp-setup/handoff.json     клиентский материал, 0600
/var/lib/xhttp-setup/firewall-plan.txt
/var/lib/xhttp-setup/current.json     receipt применённого состояния
~/.local/state/xhttp-setup/           TOFU и PC recovery state

Не публикуйте handoff.json, client.vless, recovery state или VLESS URI.

Ограничения

один frontend-домен, ровно одна A-запись и отсутствие AAAA;
один стабильный frontend egress IPv4 /32;
bare Xray exit; существующие Docker/Remnawave/custom firewall не мигрируются;
мастер не управляет DNS, ISPmanager site creation и provider cloud firewall;
мастер не включает PHP/FastCGI или mod_proxy; как в подтверждённом старом запуске, PHP -> FastCGI (Apache) остаётся ручной настройкой существующего сайта, а локальная [P]-canary только функционально проверяет готовый vhost;
необязательный мост версии 0.6.1 прошёл на реальном запуске setup-доступ к ISPmanager, SFTP и TLS/SNI. На проверенном 2026-08-20 узле дальнейшая проба остановилась из-за неподтверждённой reverse-proxy возможности хостинга; parser-hotfixes 0.6.2, 0.6.3 и 0.6.4 dataplane не меняют; 0.6.5 меняет только preflight: до подготовки fresh exit проверяет локальный [P] на 127.0.0.1:9, затем проверяет фактический TCP/8083 вместо случайных портов. 0.6.6 расширяет только allowlist панели на штатные serverNNN-узлы REG.RU. Нового успешного bridge E2E поэтому пока нет;
публичный CA и стабильный exact-pinned leaf поддерживаются, произвольная смена закреплённого сертификата требует явного восстановления доверия;
импорт итоговой ссылки конкретным GUI-клиентом остаётся отдельной проверкой.

Исторический успешный dataplane и отдельный отрицательный live-результат Release v0.6.1 описаны без адресов и секретов в docs/reference-audit-2026-08-19.md.

Правила REG.RU

Справка REG.RU продолжает перечислять proxy-сервисы среди запрещённого контента на виртуальном хостинге. Техническая работоспособность схемы не даёт разрешения провайдера и не гарантирует отсутствие блокировки. Используйте её только после письменного разрешения REG.RU. Другой разрешающий хостинг потребует отдельного adapter/advanced workflow: минимальный PC-мастер принимает только REG.RU ISPmanager/SFTP contract и не является универсальным drop-in клиентом:

https://help.reg.ru/support/hosting/zakaz-hostinga-rabota-s-uslugoy/sovety-po-vyboru-tarifa-hostinga

Мастер не обходит антифрод, лимиты или блокировки, не ротирует домены и не маскирует трафик под сторонний сайт.

Сборка release

python3 scripts/build.py
python3 scripts/build_windows_bundle.py
python3 scripts/verify_built_artifacts.py
python3 -m unittest discover -s tests -v

Release CI затем повторяет обе сборки из чистого dist, сравнивает SHA-256 первого и второго результата, проверяет sidecar-файлы, содержимое ZIP и байтовое совпадение INSTRUCTION.txt. Один успешный запуск сборщика без этой повторной проверки не считается доказательством воспроизводимого артефакта.

Release v0.6.6 считается готовым к установке только после успешного workflow и публикации ровно пяти проверенных файлов:

xhttp-setup-0.6.6.pyz
xhttp-setup-0.6.6.pyz.sha256
xhttp-setup-0.6.6-windows-wsl.zip
xhttp-setup-0.6.6-windows-wsl.zip.sha256
INSTRUCTION.txt

GitHub workflow публикует только tag вида vX.Y.Z. Release tags и опубликованные артефакты должны быть immutable. Публикация выполняется только после явной отправки тега; deployment серверов workflow не выполняет.

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
docs		docs
scripts		scripts
tests		tests
windows		windows
xhttp_setup		xhttp_setup
.gitattributes		.gitattributes
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
docs-release-install.txt		docs-release-install.txt
pyproject.toml		pyproject.toml

Navigation Menu

Repository navigation

About

Repository files navigation

XHTTP Setup

Быстрый запуск на Windows

Что нужно ввести

Что PC-мастер делает автоматически

Необязательный SSH-мост в текущем PC-мастере

Требования перед запуском

Существующий frontend

Чистый exit

Необязательный мост

TOFU: точный компромисс

Повторный запуск и восстановление

Запуск на Linux

Расширенные режимы

Безопасность изменений frontend

Файлы на exit и локальном компьютере

Ограничения

Правила REG.RU

Сборка release

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

XHTTP Setup

Быстрый запуск на Windows

Что нужно ввести

Что PC-мастер делает автоматически

Необязательный SSH-мост в текущем PC-мастере

Требования перед запуском

Существующий frontend

Чистый exit

Необязательный мост

TOFU: точный компромисс

Повторный запуск и восстановление

Запуск на Linux

Расширенные режимы

Безопасность изменений frontend

Файлы на exit и локальном компьютере

Ограничения

Правила REG.RU

Сборка release

About

Resources

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages