Установка

В не зависимости от выбраного вида установки hbf-server, необходимо настроить общие переменные окружения:

HBF_SERVER - IP-адрес hbf-server.

Setup HBF_SERVER
export HBF_SERVER=0.0.0.0

HBF_SERVER_PORT - порт, используемый hbf-server.

Setup HBF_SERVER_PORT
  export HBF_SERVER_PORT=9650

DNS_SERVER - Список доверенных IP-адресов DNS серверов.

Setup DNS_SERVER
export DNS_SERVER=['8.8.8.8']

VERSION - версия агента, которую пользователь хочет установить.

Setup VERSION
export VERSION=1.9.1

docker
deb
rpm
source
ansible

Перед развертыванием убедитесь, что у вас установлен docker:

Get docker version
docker -v

Клонируем репозиторий, переходим в директорию репозитория и переключаемся на тег необходимой версии командой:

Git setup
git clone https://github.com/H-BF/sgroups
cd sgroups
git fetch --tags --all
git checkout tags/v${VERSION}

Создайте конфигурационный файл для hbf-agent командой:

Configuration file setup
cat <<EOF > config-agent.yaml
---
graceful-shutdown: 10s

logger:
  level: DEBUG

fqdn-rules:
  strategy: dns

extapi:
  svc:
    def-daial-duration: 10s
    sgroups:
      dial-duration: 3s
      address: 'tcp://${HBF_SERVER}:${HBF_SERVER_PORT}'
      sync-status:
        interval: 3s #mandatory
        push: true

netlink:
  watcher: #netlink watcher
    linger: 1s

base-rules:
  networks: ['${HBF_SERVER}/32']

dns:
  nameservers: ${DNS_SERVER}
  proto: tcp
  port: 53
  dial-duration: 3s
  read-duration: 5s #default
  write-duration: 5s #default 5s
  retries: 5 #default 1
  retry-timeout: 3s #default 1s

telemetry:
  useragent: "string"
  endpoint: 0.0.0.0:9660
  metrics:
    enable: true
  healthcheck:
    enable: true
EOF

Собираем образ hbf-agent командой:

docker build -f docker/Dockerfile.agent --tag to-nft:v${VERSION} .

Запускаем hbf-agent командой:

docker run \
-d \
-v ./config-agent.yaml:/opt/swarm/etc/to-nft/config-agent.yaml \
--name hbf-agent \
--entrypoint "/app/bin/to-nft" \
--privileged \
--user=0 \
to-nft:v${VERSION} -config /opt/swarm/etc/to-nft/config-agent.yaml

Настроим необходимые переменные окружения командой:

Environment setup
export PACKAGE_TYPE=deb
export URL=https://github.com/H-BF/sgroups/releases/download
export RELEASE=v$VERSION/to-nft-$VERSION-any.$PACKAGE_TYPE

Скачиваем и устанавливаем deb-пакет командой:

Install deb package
sudo wget -O /tmp/to-nft.deb $URL/$RELEASE
sudo dpkg -i /tmp/to-nft.deb

Создайте конфигурационный файл для hbf-agent командой:

Configuration file setup
mkdir -p /opt/swarm/etc/to-nft
cat <<EOF > /opt/swarm/etc/to-nft/config-agent.yaml
---
graceful-shutdown: 10s

logger:
  level: DEBUG

fqdn-rules:
  strategy: dns

extapi:
  svc:
    def-daial-duration: 10s
    sgroups:
      dial-duration: 3s
      address: 'tcp://${HBF_SERVER}:${HBF_SERVER_PORT}'
      sync-status:
        interval: 3s #mandatory
        push: true

netlink:
  watcher: #netlink watcher
    linger: 1s

base-rules:
  networks: ['${HBF_SERVER}/32']

dns:
  nameservers: ${DNS_SERVER}
  proto: tcp
  port: 53
  dial-duration: 3s
  read-duration: 5s #default
  write-duration: 5s #default 5s
  retries: 5 #default 1
  retry-timeout: 3s #default 1s

telemetry:
  useragent: "string"
  endpoint: 0.0.0.0:9660
  metrics:
    enable: true
  healthcheck:
    enable: true
EOF

Запустите сервис hbf-server.service командой:

Agent service start
systemctl enable hbf-agent.service
systemctl start hbf-agent.service

Настроим необходимые переменные окружения командой:

Environment setup
export PACKAGE_TYPE=rpm
export URL=https://github.com/H-BF/sgroups/releases/download
export RELEASE=v$VERSION/to-nft-$VERSION-any.$PACKAGE_TYPE

Создайте конфигурационный файл для hbf-agent командой:

Configuration file setup
mkdir -p /opt/swarm/etc/to-nft
cat <<EOF > /opt/swarm/etc/to-nft/config-agent.yaml
---
graceful-shutdown: 10s

logger:
  level: DEBUG

fqdn-rules:
  strategy: dns

extapi:
  svc:
    def-daial-duration: 10s
    sgroups:
      dial-duration: 3s
      address: 'tcp://${HBF_SERVER}:${HBF_SERVER_PORT}'
      sync-status:
        interval: 3s #mandatory
        push: true

netlink:
  watcher: #netlink watcher
    linger: 1s

base-rules:
  networks: ['${HBF_SERVER}/32']

dns:
  nameservers: ${DNS_SERVER}
  proto: tcp
  port: 53
  dial-duration: 3s
  read-duration: 5s #default
  write-duration: 5s #default 5s
  retries: 5 #default 1
  retry-timeout: 3s #default 1s

telemetry:
  useragent: "string"
  endpoint: 0.0.0.0:9660
  metrics:
    enable: true
  healthcheck:
    enable: true
EOF

Скачиваем и устанавливаем rpm-пакет командой:

Install rpm package
sudo wget -O /tmp/to-nft.rpm $URL/$RELEASE
sudo yum localinstall /tmp/to-nft.rpm

Запустите сервис hbf-agent.service командой:

Agent service start
systemctl enable hbf-agent.service
systemctl start hbf-agent.service

Перед развертыванием, необходимо создать директории для хранения бинарного файла и файлов конфигурации командой:

Environment setup
mkdir -p /opt/swarm/sbin
mkdir -p /opt/swarm/etc/to-nft

Клонируем репозиторий, переходим в директорию репозитория, переключаемся на тег необходимой версии и Создайте необходимые директории командой:

Git setup
git clone https://github.com/H-BF/sgroups
cd sgroups
git fetch --tags --all
git checkout tags/v${VERSION}
make to-nft platform=linux/amd64
cp bin/to-nft /opt/swarm/sbin/hbf-agent

Создайте конфигурационный файл для hbf-agent командой:

Configuration file setup
cat <<EOF > /opt/swarm/etc/to-nft/config-agent.yaml
---
graceful-shutdown: 10s

logger:
  level: DEBUG

fqdn-rules:
  strategy: dns

extapi:
  svc:
    def-daial-duration: 10s
    sgroups:
      dial-duration: 3s
      address: 'tcp://${HBF_SERVER}:${HBF_SERVER_PORT}'
      sync-status:
        interval: 3s #mandatory
        push: true

netlink:
  watcher: #netlink watcher
    linger: 1s

base-rules:
  networks: ['${HBF_SERVER}/32']

dns:
  nameservers: ${DNS_SERVER}
  proto: tcp
  port: 53
  dial-duration: 3s
  read-duration: 5s #default
  write-duration: 5s #default 5s
  retries: 5 #default 1
  retry-timeout: 3s #default 1s

telemetry:
  useragent: "string"
  endpoint: 0.0.0.0:9660
  metrics:
    enable: true
  healthcheck:
    enable: true
EOF

Создайте конфигурационный файл для hbf-server.agent командой:

Agent service setup
cat <<EOF > /etc/systemd/system/hbf-agent.service
[Unit]
Description=hbf agent
After=network.target

[Service]
ExecStart=/opt/swarm/sbin/hbf-agent --config=/opt/swarm/etc/to-nft/config-agent.yaml
Restart=always
RestartSec=5
Delegate=yes
KillMode=process
OOMScoreAdjust=-999
LimitNOFILE=1048576
LimitNPROC=infinity
LimitCORE=infinity

[Install]
WantedBy=multi-user.target
EOF

Запустите сервис hbf-server.service командой:

Agent service start
systemctl enable hbf-agent.service
systemctl start hbf-agent.service

Перед развертыванием убедитесь, что у вас установлен ansible:

ansible-playbook --version

Далее убедитесь, что вы корректно указали версию, установив переменную VERSION без символа 'v'. Следующим шагом склонируйте репозиторий:

git clone https://github.com/H-BF/ansible
cd ansible
git fetch --tags --all
git checkout tags/v${VERSION}

Требования

Перед выполнением ansible-playbook убедитесь, что текущая версия дистрибутива ОС имеет необходимый пакет linux-headers. Как пример, на Ubuntu/Debian, вы можете проверить это с помощью команды:

apt search linux-headers-$(uname -r)

В случае, если такой пакет существует вывод будет следующим:

Sorting... Done
Full Text Search... Done
linux-headers-5.10.0-26-amd64/oldstable, now 5.10.197-1 amd64 [installed]
    Header files for Linux 5.10.0-26-amd64

Сообщение linux-headers-5.10.0-26-amd64/oldstable, now 5.10.197-1 amd64 [installed] говорит о том, что необходимый пакет заголовков найден. В противном случае необходимо обновить версию ядра до ближайшей версии имеющей пакет linux-headers-$(uname -r)

Использование

Перед запуском плейбука убедитесь, что вы добавили необходимые хосты в env/hosts. Чтобы выполнить плейбук, запустите:

ansible-playbook main.yaml

Удаление

Чтобы удалить определенные компоненты hbf-agent, установите переменную <component>_enabled: false. Если вы удаляете сам hbf-agent, все правила, созданные им в nft, будут автоматически удалены.

Параметры конфигурационного файла

Для настройки агентов требуется использовать конфигурационный файл, который содержит поля, позволяющие настраивать параметры в соответствии с потребностями пользователей. Так же есть алтьтернативный способ - переменные окружения. Обратите внимание, что переменные окружения являются более приоритетными, чем параметры из файла. Так же часть параметров можно настроить через файл, а часть через переменные окружения.

Параметры файла config-agent.yaml
Параметр / Переменная окружения	Описание	Тип	Обязательно
exit-on-success `NFT_EXIT_ON_SUCCESS`	Завершение процесса, если успешно применилась конфигурация для nft. Значение по умолчанию: `false`.	Boolean	Нет
continue-on-failure `NFT_CONTINUE_ON_FAILURE`	В случае ошибки на уровне job, агент не завершает свою работу (идет на цикл перезапуска своих job). Значение по умолчанию: `true`	Boolean	Нет
logger.level `NFT_LOGGER_LEVEL`	Уровень логгирования. Допустимые значения: `TRACE`, `DEBUG`, `INFO`, `WARN`, `ERROR`, `FATAL`, `PANIC`.	String	Нет
graceful-shutdown `NFT_GRACEFUL_SHUTDOWN`	Определяет период времени, в течение которого процесс агента должен корректно завершиться. По истечению периода, процесс завершиться с кодом 1. Значение по умолчанию: `10s`	String	Нет
netns `NFT_NETNS`	Имя сетевого namespac'a.	String	Нет
netlink.watcher.linger `NFT_NETLINK_WATCHER_LINGER`	Время, в течение которого из netlink'а ожидаются события. Минимальное значение: `1s`.	String
base-rules.networks `NFT_BASE_RULES_NETWORKS`	Список IP адресов, к которым всегда должен egress быть доступ. Не рекомендуется устанавливать в качестве значения пустой список.	List	Да
fqdn-rules.strategy `NFT_FQDN_RULES_STRATEGY`	Способ обработки fqdn-правил. Значение по умолчанию: `dns`. Допустимые значения: `dns`, `ndpi`, `combine`.	String	Нет
dns.nameservers `NFT_DNS_NAMESERVERS`	Список доверенных IP-адресов DNS серверов.	List	Да
dns.proto `NFT_DNS_PROTO`	Протокол L4, используемый DNS сервером. Значение по умолчанию: `udp`. Допустимые значения: `udp`, `tcp`.	String	Да
dns.port `NFT_DNS_PORT`	Порт, используемый DNS сервером. Значение по умолчанию: `53`.	Int	Да
dns.retries `NFT_DNS_RETRIES`	Количество повторных запросов к DNS серверу при сбое. Значение по умолчанию: `3`.	Int	Нет
dns.retry-timeout `NFT_DNS_RETRY_TIMEOUT`	Период между повторным запросом DNS сервера при сбое. Значение по умолчанию: `1s`.	String	Нет
dns.dial-duration `NFT_DNS_DIAL_DURATION`	Период времени подключения к DNS серверу. Значение по умолчанию: `3s`.	String	Нет
dns.write-duration `NFT_DNS_WRITE_DURATION`	Максимальное временя ожидания ответа от DNS сервера при запросе резолва FQDN. Значение по умолчанию: `5s`.	String	Нет
dns.read-duration `NFT_DNS_READ_DURATION`	Максимальное временя ожидания ответа от DNS сервера. Значение по умолчанию: `5s`.	String	Нет
extapi.svc.def-dial-duration `NFT_EXTAPI_SVC_DEF_DIAL_DURATION`	Длительность ожидания подключения к службе.	String	Нет
extapi.svc.sgroups.address `NFT_EXTAPI_SVC_SGROUPS_ADDRESS`	IP адрес hbf-сервера.	String	Да
extapi.svc.sgroups.dial-duration `NFT_EXTAPI_SVC_SGROUPS_DIAL_DURATION`	Продолжительность ожидания подключения к hbf-серверу.	String	Нет
extapi.svc.sgroups.sync-status.interval `NFT_EXTAPI_SVC_SGROUPS_SYNC_STATUS_INTERVAL`	Период синхронизации с hbf-сервером. Значение по умолчанию: `10s`.	String	Да
extapi.svc.sgroups.sync-status.push `NFT_EXTAPI_SVC_SGROUPS_SYNC_STATUS_PUSH`	Использовать push модель для синхронизации с hbf-сервером. Значение по умолчанию: `false`.	Boolean	Нет
telemetry.endpoint `NFT_TELEMETRY_ENDPOINT`	IP адрес и порт, для доступа к метрикам. Рекомендуемое значение: `0.0.0.0:9660`.	String	Нет
telemetry.metrics.enable `NFT_TELEMETRY_METRICS_ENABLE`	Включить/Отключить возможность получения метрик. Значение по умолчанию: `true`. Пример получения метрик: `curl 0.0.0.0:9660/metrics`.	Boolean	Нет
telemetry.healthcheck.enable `NFT_TELEMETRY_HEALTHCHECK_ENABLE`	Включить/Отключить возможность получения информации о статусе hbf-агента. Значение по умолчанию: `true`. Пример получения статуса: `curl 0.0.0.0:9660/healthcheck`.	Boolean	Нет
telemetry.useragent `NFT_TELEMETRY_USERAGENT`	Позволяет устанавливать метку в параметры метрик	String	Нет
telemetry.profile.enable `NFT_TELEMETRY_PROFILE_ENABLE`	Включить/Отключить возможность получения профиля hbf-агента. Значение по умолчанию: `true`. Пример получения профиля: `curl 0.0.0.0:9660/debug/pprof/goroutine?debug=2`.	Boolean	Нет

Установка

Требования​

Использование​

Удаление​

Параметры конфигурационного файла​

Требования

Использование

Удаление

Параметры конфигурационного файла