https://github.com/hexresearch/hexcapt
https://github.com/hexresearch/hexcapt
Last synced: over 1 year ago
JSON representation
- Host: GitHub
- URL: https://github.com/hexresearch/hexcapt
- Owner: hexresearch
- License: other
- Created: 2016-10-29T18:15:13.000Z (over 9 years ago)
- Default Branch: master
- Last Pushed: 2016-11-13T10:54:58.000Z (over 9 years ago)
- Last Synced: 2025-01-09T03:56:54.313Z (over 1 year ago)
- Language: Haskell
- Size: 62.5 KB
- Stars: 0
- Watchers: 13
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 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```
## Конфигурирование
1. Убедиться, что бинарник ```ndnproxy``` находится в системном пути и доступен
1. Настройки сервиса находятся в файле ```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]
```