freeradius/packaging/hosted/README.md

Hosted установка (bare-metal / VM)

Для чего этот репозиторий

Это сборка и поставка кастомного FreeRADIUS 3.2.x для hotspot / captive-portal сценариев. Прикладного кода здесь нет: репозиторий собирает апстримный FreeRADIUS с дополнительным модулем rlm_raw, накладывает конфиги и доставляет результат в двух видах - bare-metal (этот каталог) и Kubernetes (Helm-чарт в charts/freeradius).

Как это работает

1. Точки доступа / hotspot-шлюзы (NAS) шлют RADIUS-запросы. Статически клиенты не прописаны - они резолвятся динамически. clients.conf объявляет сеть 0.0.0.0/0 как динамическую (client dynamic).
2. Когда приходит пакет от неизвестного NAS, FreeRADIUS вызывает виртуальный сервер dynamic_clients (sites-enabled/dynamic-clients). Тот ищет NAS по NAS-Identifier в таблице nas PostgreSQL: если запись есть - берёт из БД secret/shortname и определяет клиента на лету; если нет - идёт в REST к сервису hotspotter.
3. Авторизация абонента идёт в site default через SQL (схема RADIUS: radcheck, radreply, radacct, ...) и/или REST. Hotspotter получает hotspot-group (= Called-Station-Id) и hotspot-id (= NAS-Identifier) и решает, пускать ли.
4. Профиль урезан под задачу: отключены eap, inner-tunnel, proxy_rate_limit, включён delay_reject.

Зачем нужен rlm_raw

NAS-Identifier и Called-Station-Id - строковые RADIUS-атрибуты, в которые hotspot-шлюзы кладут идентификатор точки/группы. Это значение должно совпадать байт-в-байт с nas.shortname в БД и с записями в hotspotter.

Штатный xlat %{NAS-Identifier} отдаёт значение уже после разбора и нормализации FreeRADIUS (атрибут декодируется по словарю, к строке применяется обработка). Для произвольных байтов и нестандартных форматов это меняет значение и ломает поиск.

Модуль rlm_raw добавляет xlat %{raw:...}, который возвращает атрибут ровно так, как его прислал NAS, без перекодирования. Все ключевые конфиги (dynamic-clients, mods-enabled/rest) построены на %{raw:Called-Station-Id} и %{raw:NAS-Identifier}, поэтому модуль обязателен - без него конфиг просто не загрузится. Именно поэтому FreeRADIUS пересобирается из исходников с rlm_raw, а не ставится из стандартного apt.

Что в этом каталоге

Файл	Назначение
.env	Версия пакета: FREERADIUS_TAG (ставится как <tag>+git).
.env_cnf_example	Шаблон для .env_cnf. Скопировать и заполнить.
.env_cnf	Локальные секреты/хосты. В git не попадает (gitignore).
config/	radiusd.conf, dictionary, clients.conf, mods/sites.
install.sh	Первичная установка (root).
update.sh	Смена версии пакета (root).
cron/radius-renew.sh	Ежемесячный перевыпуск сертификатов.

Этот бандл публикуется CI как generic-пакет: https://git.ahax86.ru/api/packages/pub/generic/freeradius-hosted/<version>/freeradius-hosted.tar.gz

Требования

• Ubuntu 24.04 (noble), root.
• Доступ к git.ahax86.ru, к PostgreSQL и к REST-сервису hotspotter.
• Нужная версия .deb уже опубликована в Debian-реестре Gitea (CI собирает её первой).

Установка

cp .env_cnf_example .env_cnf
$EDITOR .env_cnf        # заполнить хосты/порты/креды
sudo ./install.sh

install.sh подключает Debian-реестр Gitea, ставит запиненные пакеты (apt-mark hold), рендерит sites-enabled/default, mods-enabled/rest и mods-enabled/sql из .env_cnf, копирует статические конфиги, включает delay_reject, ставит systemd-юнит и cron.

Переменные .env_cnf:

Переменная	Смысл
FR_MAIN_PORT / FR_ACC_PORT	UDP-порты auth / accounting.
FR_API_HOST / FR_API_PORT	Endpoint REST hotspotter.
FR_PG_HOST / FR_PG_PORT	Хост / порт PostgreSQL.
FR_PG_USER / FR_PG_PASS / FR_PG_DB	Креды / база PostgreSQL.

Приватный реестр

Если реестр pub не публичный, перед запуском задайте токен:

export DEB_AUTH="<gitea-user>:<token-с-read:package>"
sudo -E ./install.sh

Прочие переопределения (значения по умолчанию): DEB_REGISTRY=https://git.ahax86.ru/api/packages/pub/debian, DEB_DISTRIBUTION=noble, DEB_COMPONENT=main.

Смена версии

# поменять FREERADIUS_TAG в .env, затем:
sudo ./update.sh

update.sh: apt-mark unhold → установка нужной версии → apt-mark hold → перезапуск.

Удаление

sudo apt-mark unhold libfreeradius3 freeradius-common freeradius-postgresql \
  freeradius-rest freeradius-utils freeradius
sudo apt-get purge -y freeradius freeradius-common freeradius-config \
  freeradius-python3 libfreeradius3 freeradius-postgresql freeradius-rest freeradius-utils
sudo rm -rf /etc/freeradius /usr/lib/freeradius

Проверка в Docker

docker build . -t hosted:test -f Dockerfile
docker run -ti -p 1812:1812/udp -p 1813:1813/udp hosted:test /bin/bash