voidlizard/hexcapt.md

## hexcapt.md

      
    Raw
  

              hexcapt.md
            
          
    hexcapt

Краткое описание работы

Сервис hexcapt осуществляет работу captive portal следующим образом:

Маркирует сетевые соединения, используя заданный при помощи API уровень доступа (см.конфигурирование)
Запускает заданное число DNS прокси с заданными настройками, для осуществления различного
разрешения адресов в зависимости от заданных режимов
Осуществляет перенаправление (DNAT) DNS запросов на заданный инстанс DNS прокси в зависимости
от заданного для MAC адреса (пользователя) уровня доступа
Осуществляет фильтрацию проходящего наружу трафика в зависимости от уровня доступа (см.
modes/mode/forward )
Осуществляет перенаправление (DNAT) входящего для заданных портов на локальный сервис,
в случае, если это указано в настройках режимов

Таким образом, для конфигурации по умолчанию выполняется следующее:
Пользователи с уровнем доступа по умолчанию (0):

DNS запросы перенаправляются на локальный DNS прокси
Все адреса разрешаются на локальный адрес портала (192.168.2.1)
Все HTTP запросы перенаправляются на локальный сервер на порту 81
Соединения наружу блокируются

Пользователи с уровнем доступа 1:

DNS запросы перенаправляются на локальный DNS прокси
Адреса (кроме исключений) разрешаются вышестоящим DNS
Адреса (исключения) разрешаются на локальный адрес портала (192.168.2.1)
Все HTTP запросы наружу разрешены (кроме списка исключений, по DNS(!))
Прочие соединения наружу блокируются

Пользователи с уровнем доступа 2:

DNS запросы перенаправляются на локальный DNS прокси
Адреса (кроме исключений) разрешаются вышестоящим DNS
Разрешены HTTP, HTTPS соединения наружу
Прочие соединения наружу блокируются

Данное поведение является настраиваемым, например, для добавления перенаправления
HTTP на локальный сервер в режиме 1 необходимо добавить:
	redirect:
		- [tcp, 80, 81]

в соответствующую секцию конфига:
modes:
    - mode:
        marks: [1]
        redirect:
            - [tcp, 80, 81]
        forward:
            - [tcp, 443]


Сервис самостоятельно создает необходимые цепочки и правила iptables в следующих таблицах:

mangle / PREROUTING (маркирование трафика)
nat / PREROUTING (DNAT)
filter / INPUT (фильтр входящих соединений)
filter / FORWARD (разрешение роутинга в зависимости от режимов)

Компоненты

hexcapt

Основной сервис. Реализует API, создает необходимые правила iptables/netfilter
hexcapt-client

Клиент для сервиса. Взаимодействует с сервисом по протоколу HTTP через API (см. ниже)
hexcapt.yaml

Конфигурационный файл сервиса (см. ниже)
hexcapt.service

Файл сервиса systemd.
ndnproxy

Конфигурируемый, легковесный DNS прокси, использующийся для организации
Captive Portal.
libndm.so

Shared library, необходимая ndnproxy (должна находиться в LD_PATH).
API

Для управления сервисом существует HTTP API:

HTTP GET http://URL:PORT/hexcapt/set-access?mac-addr=MAC&mark=MARK


Пример:

curl -i http://localhost:10011/hexcapt/set-access?mac-addr=fe:66:3f:e6:e5:e3&mark=1


Либо можно использовать консольный клиент:

hexcapt-client

Usage: hexcapt-client [--url ARG] --mac ARG --access ARG
  hexcapt client utility

Available options:
  -h,--help                Show this help text
  --url ARG                hexcapt API URL
  --mac ARG                MAC address to set acess
  --access ARG             access mark


Пример:
hexcapt-client --mac C1:34:2D:51:C4:E4  --access 1
Данный клиент по умолчанию считает, что сервис hexcapt работает на той же машине, что
и клиент. Порт API, на котором слушает сервер, hexcapt-client ищет в конфигурационных
файлах hexcapt.yaml в тех же местах, и в той же последовательности, что и сервис.
Возможно явно задать URL API при помощи параметра --url в виде http://URL:PORT.
Установка


Скопировать nexcapt в /usr/bin или /usr/local/bin
Скопировать nexcapt-client в /usr/bin или /usr/local/bin
Скопировать hexcapt.yaml в /etc
Скопировать ndnproxy в /usr/bin или /usr/local/bin
Скопировать libndm.so в /usr/lib или /usr/local/lib
Запустить ldconfig
Убедиться, что libndm.so доступен в LD_PATH
Скопировать hexcapt.service в /etc/systemd/system
Проверить, что путь к hexcapt в hexcapt.service соответствует реальному положению дел
Выполнить systemctl daemon-reload
Выполнить systemctl enable hexcapt

Запуск

Сервис должен стартовать автоматически при загрузке системы при помощи systemd.
Ручной старт/стоп/перазапуск осуществляются при помощи команды systemctl start|stop|restart hexcapt
Конфигурирование


Убедиться, что бинарник ndnproxy находится в системном пути и доступен
Настройки сервиса находятся в файле hexcapt.yaml

Настройки hexcapt.yaml


# порт, на котором слушает HTTP API
listen: 10011

# адрес, к которому биндится HTTP API
bind: 0.0.0.0

# частота обновления таблицы mangle
sleep: 1.0

# интерфейс локальной сети роутера
input-iface: br0

# локальный IP роутера
local-ip:  192.168.2.1

# режимы работы сервиса
modes:

    - mode:
	    
# без определенных марок - режим по умолчанию.
# (некоторые) настройки отсюда добавляются в прочие режимы,
# например, local-domains

        marks: []

#  данные домены будут резолвится на локальный адрес
#  для указанных режимов (если марка не задана - то для всех режимов)
#  при задании домена в виде: *.zaycev.net
#  резолвится как сам домен, так и его поддомены.

        local-domains:
            - "clients3.google.com"
            - "connectivitycheck.android.com"
            - "geowalk.ru"
            - "start.tutu.tv"
            - "tilestream.geowalk.ru"
            - "tutu.tv"
            - "video.tutu.tv"
            - "www.geowalk.ru"
            - "www.msftncsi.com"
            - "www.tutu.tv"
            - "www.video.tutu.tv"


    - mode:
# марки,  определенныё для режима - может быть несколько
        marks: [0]

# DNAT-ы для данного режима (протокол, порт источника, порт назначения)
# может быть несколько
        redirect:
            - [tcp, 80, 81]

        local-domains: []

    - mode:
        marks: [2]
        local-domains: []
        forward:
            - [tcp, 443]
            - [tcp, 80]


# инстансы ndnproxy
ndnproxy:


    - instance:
# TCP порт, на котором слушает прокси
        tcp-port: 10053

# UDP порт, на котором слушает прокси
        udp-port: 10053
# марки, по которым выполняется перенаправление (DNAT)
# на этот инстанс прокси
        marks: [0]

# заданные статические адреса (маски поддерживаются)
        static-a:
            - ['*', 192.168.2.1]