Установка сервера REST API для управления DNS (пакет elles-dns-api)

Схема развертывания

elles-dns-api поддерживает развертывание с использованием deb-пакета:

  • в полностью автоматическом режиме — на одном хосте с контроллером домена «Эллес» с работающими KDC, LDAP- и DNS-сервером;

  • с дополнительными действиями по запуску скрипта настройки и переносу требуемых файлов — на отдельном хосте.

elles dns api deployment
Рис. 1. Схема развертывания elles-dns-api

Описание элементов схемы:

  1. Клиенты (curl, веб-интерфейс, скрипты) отправляют HTTPS-запросы к серверу elles-dns-api, который работает как systemd-сервис и установлен на контроллере домена или отдельном хосте.

  2. Сервер elles-dns-api аутентифицирует клиентов через SPNEGO/Kerberos, используя keytab-файл для HTTP-SPN. Для выполнения операций с DNS-зонами и службой каталогов elles-dns-api взаимодействует с контроллером домена «Эллес» по протоколам LDAP (для чтения/записи DNS-записей) и DCE/RPC (для управления зонами). Все аутентификационные ключи (keytab) и TLS-сертификаты передаются с контроллера домена на сервер elles-dns-api.

  3. При развертывании на контроллере домена запускается скрипт elles-dns-api-setup, который автоматически создает служебные учетные записи, настраивает их SPN, генерирует keytab-файлы и выдает сертификаты для безопасного взаимодействия. При развертывании на отдельной машине скрипт запускается вручную на контроллере домена, после чего файлы копируются на API-хост.

Список служебных учетных записей, используемых сервером elles-dns-api:

Учетная запись Назначение SPN

svc-dnsel-http

SPNEGO (Kerberos-аутентификация HTTP-клиентов)

HTTP/<api-fqdn>

svc-dnsel-ldap

LDAP-операции с Active Directory

—
(используется целевой SPN контроллера домена)

svc-dnsel-rpc

DNS Server Management Protocol (RPC)

—

Предварительные требования

Перед установкой:

  1. При установке на одном хосте с контроллером домена — убедитесь, что «Эллес» работает в режиме контроллера домена:

    sudo systemctl status inno-samba.service

    Ожидаемый вывод:

    ● inno-samba.service - Samba AD Daemon
   Loaded: loaded (/lib/systemd/system/inno-samba.service; enabled; vendor preset: enabled)
    Active: active (running) since ...

  2. Убедитесь, что с хоста доступны пакеты krb5-user, sasl2-bin, libsasl2-modules-gssapi-mit, ldap-utils, gettext-base. Они добавляются автоматически как зависимости при установке пакета.

Установка пакета

Установите пакет elles-dns-api:

  • при установке из репозитория:

    sudo apt install elles-dns-api -y

  • при установке из архива или копировании вручную укажите путь к распакованным файлам и имя пакета; например:

    cd /path/to/package
sudo apt install ./elles-dns-api_1.22.0-1_amd64.deb -y

    или

    cd /path/to/package
sudo dpkg -i elles-dns-api_*.deb
sudo apt install -f   # Устанавливает зависимости: krb5-user, sasl2-bin,
                      # libsasl2-modules-gssapi-mit, ldap-utils, gettext-base

В процессе установки пакета автоматически

  • создаются:

    Путь Назначение

    /usr/sbin/elles-dns-api

    Исполняемый файл сервера

    /usr/sbin/elles-dns-api-setup

    Скрипт настройки Active Directory и генерации конфигурации

    /usr/share/elles-dns-api/config.yaml.template

    Шаблон конфигурации для заполнения скриптом настройки

    /etc/elles-dns-api/config.yaml

    Пример конфигурации (до запуска скрипта настройки)

    /etc/elles-dns-api/policy.csv

    RBAC-политики Casbin

    /etc/elles-dns-api/rbac_model.conf

    RBAC-модель Casbin

    /etc/elles-dns-api/keytabs/

    Каталог для keytab-файлов (пустой до запуска скрипта настройки)

    /var/lib/elles-dns-api/

    Рабочий каталог

    /var/log/elles-dns-api/

    Каталог для лог-файлов

    dnsel (user/group)

    Системный пользователь

    /lib/systemd/system/elles-dns-api.service

    Systemd-юнит
    Сервис elles-dns-api не запускается автоматически после установки, так как для его работы требуются объекты, создаваемые скриптом настройки elles-dns-api-setup на контроллере домена.

  • назначаются владельцы и права доступа:

    Путь Владелец Права

    /etc/elles-dns-api/

    dnsel:dnsel

    0750

    /etc/elles-dns-api/config.yaml

    dnsel:dnsel

    0640

    /etc/elles-dns-api/policy.csv

    dnsel:dnsel

    0640

    /etc/elles-dns-api/rbac_model.conf

    dnsel:dnsel

    0640

    /etc/elles-dns-api/keytabs/

    dnsel:dnsel

    0700

    /etc/elles-dns-api/keytabs/*.keytab

    dnsel:dnsel

    0600

    /etc/elles-dns-api/keytabs/api-server.key

    dnsel:dnsel

    0600

    /etc/elles-dns-api/keytabs/api-server.crt

    dnsel:dnsel

    0644

Запуск скрипта настройки на контроллере домена

Скрипт elles-dns-api-setup подготавливает среду для работы elles-dns-api.

Он должен быть запущен на работающем контроллере домена «Эллес» от имени root, независимо от фактического размещения elles-dns-api:

  • если elles-dns-api развертывается на одном хосте с контроллером домена, скрипт запускается локально;

  • если elles-dns-api развертывается на отдельном хосте, требуется скопировать скрипт elles-dns-api-setup на хост с работающим контроллером домена «Эллес», запустить его, а затем перенести созданные им файлы на целевой хост.

Запуск

Чтобы запустить скрипт после установки пакета, выполните:

sudo elles-dns-api-setup

Флаги

Варианты запуска скрипта с флагами:

  • если требуется переопределить FQDN для хоста, на котором развертывается сервер REST API:

    sudo elles-dns-api-setup --api-host dc1.example.com

  • если требуется переопределить каталог установки «Эллес»:

    sudo elles-dns-api-setup --samba-dir /usr/local/samba

  • если требуется переопределить целевой контроллер домена, с которым будет работать сервер REST API (отличный от того, на котором запускается скрипт):

    sudo elles-dns-api-setup --target-dc dc2.example.com

  • если требуется повторно сформировать и заменить существующие keytab-файлы и файлы TLS-сертификата:

    sudo elles-dns-api-setup --force

  • если не требуется выполнять проверку корректности взаимодействия по LDAP/RPC в конце работы скрипта:

    sudo elles-dns-api-setup --skip-verify

Переменные окружения

Параметры работы скрипта elles-dns-api-setup можно переопределить с помощью переменных окружения:

Переменная Описание По умолчанию

REALM

Kerberos-область (Realm) домена. Используется для формирования SPN, аутентификации LDAP/RPC и конфигурации Kerberos

Автоматически определяется из /etc/krb5.conf

SPNEGO_SVC_USER

Имя служебной учетной записи в Active Directory для SPNEGO-аутентификации HTTP-клиентов

svc-dnsel-http

LDAP_SVC_USER

Имя служебной учетной записи в Active Directory для GSSAPI-аутентификации при подключении к LDAP-серверу

svc-dnsel-ldap

DNSRPC_SVC_USER

Имя служебной учетной записи в Active Directory для аутентификации в протоколе DCE/RPC (MS-DNSP)

svc-dnsel-rpc

KRB5_CONFIG

Путь к файлу krb5.conf, используемому клиентом Kerberos

/etc/krb5.conf
(определяется автоматически: предпочтительно /etc/krb5.conf, если недоступен — копируется из «Эллес»)

Пример запуска с переменными окружения:

REALM=EXAMPLE.COM \
LDAP_SVC_USER=svc-dns-ldap \
DNSRPC_SVC_USER=svc-dns-rpc \
sudo elles-dns-api-setup

Шаги выполнения

В процессе работы скрипт идемпотентно:

  1. Определяет параметры среды:

    • Kerberos realm и Base DN — из /etc/krb5.conf;

    • FQDN текущего контроллера домена — с помощью hostname -f;

    • SID группы DNSAdmins — с помощью samba-tool group show DNSAdmins;

    • путь к krb5.conf — предпочитает системный /etc/krb5.conf.

  2. Выполняет действия по созданию и настройке учетных записей:

    • создает служебную учетную запись svc-dnsel-http с SPN HTTP/<fqdn>;

    • создает служебную учетную запись svc-dnsel-ldap (LDAP bind);

    • создает служебную учетную запись svc-dnsel-rpc (DNS RPC);

    • добавляет служебные учетные записи для LDAP и RPC в группу DNSAdmins;

    • устанавливает неограниченный срок действия пароля для созданных учетных записей (опция --noexpiry).

  3. Экспортирует в каталог /etc/elles-dns-api/keytabs/ keytab-файлы для созданных учетных записей:

    • spnego-svc.keytab;

    • ldap-svc.keytab;

    • dnsrpc-svc.keytab.

  4. Формирует самоподписанный TLS-сертификат для сервера REST API:

    • api-server.crt — файл сертификата;

    • api-server.key — файл ключа.

  5. Устанавливает в качестве владельца пользователя dnsel для всех файлов в каталоге /etc/elles-dns-api/keytabs/ (chown dnsel:dnsel).

  6. Устанавливает сертификаты CA в системное хранилище (trust store):

    • сертификат CA «Эллес» (/app/inno-samba/private/tls/ca.pem) → /usr/local/share/ca-certificates/elles-samba-ca.crt;

    • сертификат сервера REST API → /usr/local/share/ca-certificates/elles-api-server.crt;

    • запуск update-ca-certificates -v.

      Позволяет использовать curl без флага -k.

  7. Формирует конфигурационный файл /etc/elles-dns-api/config.yaml на основе шаблона /usr/share/elles-dns-api/config.yaml.template, подставляя фактические значения для текущей среды (realm, base_dn, SPN, пути, SID DnsAdmins).
    Создает резервную копию существующего файла config.yaml с суффиксом на основе временной метки.

  8. Проверяет корректность настройки (если при запуске не передается флаг --skip-verify):

    • GSSAPI LDAP bind от имени служебной учетной записи svc-dnsel-ldap;

    • DCE/RPC-вызов samba-tool dns zonelist от имени служебной учетной записи svc-dnsel-rpc.

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

Скрипт безопасен для повторного запуска:

  • существующие учетные записи не создаются повторно;

  • существующие SPN не дублируются;

  • если файл конфигурации config.yaml существует, перед повторной генерацией создается резервная копия с временной меткой в имени;

  • существующие keytab- и TLS-файлы создаются повторно только с флагом --force;

  • системные CA-сертификаты обновляются (идемпотентно).

Перенос файлов (при установке на отдельном хосте)

Если скрипт elles-dns-api-setup запускался на контроллере домена, а сервер устанавливается на отдельной машине, необходимо скопировать сгенерированные файлы:

  1. Скопируйте файлы с контроллера домена на целевой хост:

    scp /etc/elles-dns-api/keytabs/*.keytab \
    /etc/elles-dns-api/keytabs/api-server.{crt,key} \
    /etc/elles-dns-api/config.yaml \
    user@api-host:/tmp/

  2. На целевом хосте выполните:

    sudo mkdir -p /etc/elles-dns-api/keytabs
sudo mv /tmp/*.keytab /tmp/api-server.{crt,key} /tmp/config.yaml /etc/elles-dns-api/
sudo chown -R dnsel:dnsel /etc/elles-dns-api/keytabs
sudo chmod 700 /etc/elles-dns-api/keytabs
sudo chmod 600 /etc/elles-dns-api/keytabs/*.keytab /etc/elles-dns-api/keytabs/api-server.key
sudo chmod 644 /etc/elles-dns-api/keytabs/api-server.crt
sudo chown dnsel:dnsel /etc/elles-dns-api/config.yaml
sudo chmod 640 /etc/elles-dns-api/config.yaml

  3. При необходимости установите CA-сертификаты в системное хранилище:

    sudo cp /tmp/elles-*.crt /usr/local/share/ca-certificates/
sudo update-ca-certificates -v

  4. Проверьте корректность настройки прав доступа к keytab-файлам:

    sudo ls -la /etc/elles-dns-api/keytabs/

    Ожидаемый вывод:

    -rw------- dnsel dnsel spnego-svc.keytab
-rw------- dnsel dnsel ldap-svc.keytab
-rw------- dnsel dnsel dnsrpc-svc.keytab
-rw------- dnsel dnsel api-server.key
-rw-r--r-- dnsel dnsel api-server.crt

Настройка RBAC

После установки пакета и запуска elles-dns-api-setup конфигурационный файл /etc/elles-dns-api/config.yaml уже сгенерирован и заполнен автоматически.

При необходимости:

  • раскомментируйте и заполните SID пользователя с правами супер-администратора в секции user_roles;

  • раскомментируйте и заполните SID reader-группы в секции group_roles.

Чтобы получить SID пользователя, выполните на контроллере домена «Эллес»:

sudo /usr/local/samba/bin/samba-tool user show <username> | grep objectSid

Пример редактирования:

rbac:
  group_roles:
    S-1-5-21-3633072393-148695822-1854736953-1101:  # DNSAdmins SID (определен автоматически)
      - role_dns_admins
    S-1-5-21-710189318-681344908-1651532485-2100:  # reader group
      - role_reader
  user_roles:
    S-1-5-21-710189318-681344908-1651532485-1118:  # super-admin
      - role_super_admin

Проверка конфигурации клиента Kerberos (при установке на отдельном хосте)

Если elles-dns-api работает на отдельной машине, убедитесь, что /etc/krb5.conf содержит корректные настройки для доступа к KDC домена.

Пример файла:

[libdefaults]
    default_realm = EXAMPLE.COM
    dns_lookup_realm = false
    dns_lookup_kdc = true

[realms]
    EXAMPLE.COM = {
        kdc = dc1.example.com:88
        admin_server = dc1.example.com:749
    }

[domain_realm]
    .example.com = EXAMPLE.COM
    example.com = EXAMPLE.COM

Проверьте доступность KDC с хоста, на котором развертывается elles-dns-api:

kinit svc-dnsel-ldap@EXAMPLE.COM -k -t /etc/elles-dns-api/keytabs/ldap-svc.keytab
klist

В выводе ожидается билет для krbtgt/EXAMPLE.COM@EXAMPLE.COM.

Запуск и проверка работоспособности

После завершения настройки:

  1. Поверьте корректность конфигурации:

    sudo elles-dns-api config validate --config /etc/elles-dns-api/config.yaml

    Ожидается: 0 error(s) (могут быть предупреждения).

  2. Включите и запустите сервис elles-dns-api:

    sudo systemctl enable --now elles-dns-api.service

  3. Проверьте статус сервиса elles-dns-api:

    sudo systemctl status elles-dns-api.service

    Ожидаемый вывод:

    ● elles-dns-api.service - elles-dns-api REST API
   Active: active (running)

Просмотр логов

Проверьте логи сервиса:

sudo journalctl -u elles-dns-api -f

Ключевые сообщения, указывающие на успешный запуск:

{"msg":"Starting dnsel-cli server","version":"1.0.0+git..."}
{"msg":"ldap config","url":"ldap://dc.example.com:389"}
{"msg":"GSSAPI bind SUCCESS"}
{"msg":"rootDSE discovered","default_nc":"DC=example,DC=com"}
{"msg":"DNS context discovered","domain_container":"CN=MicrosoftDNS,DC=DomainDnsZones,..."}
{"msg":"HTTPS server listening","addr":"0.0.0.0:9443"}

Если какое-то сообщение отсутствует, см. «Устранение возможных ошибок».

Проверка доступности API

На хосте с развернутым приложением или клиенте выполните от имени пользователя с действующим билетом Kerberos:

curl --negotiate -u : \
  "https://<api-fqdn>:9443/api/v1/dns/partitions" | jq

<api-fqdn> в примере — FQDN хоста, на котором развернут сервер elles-dns-api.

Ожидаемый ответ:

{
  "partitions": [
    {"name": "DomainDnsZones", "kind": "domain", "available": true},
    {"name": "ForestDnsZones", "kind": "forest", "available": true},
    {"name": "System",         "kind": "legacy", "available": true}
  ]
}

Доступ к Swagger UI

Откройте документацию API:

https://<api-fqdn>:9443/swagger/index.html

<api-fqdn> в примере — полное доменное имя хоста, на котором развернут сервер elles-dns-api.

Убедитесь, что:

  • отображается список конечных точек;

  • при попытке вызова любого из методов запрашивается аутентификация Kerberos.

Устранение возможных ошибок

После установки и настройки сервиса elles-dns-api могут возникать ошибки, связанные с конфигурацией, правами доступа, сетевым взаимодействием или аутентификацией.

В разделе приводятся наиболее типичные проблемы и способы их устранения.

Сервис не запускается: systemctl status возвращает failed

Если команда systemctl status elles-dns-api возвращает статус "failed", проверьте логи сервиса для выявления причины:

sudo journalctl -u elles-dns-api -n 100 --no-pager

Возможные причины и способы их устранения:

Ошибка в логе Причина Решение

open /etc/elles-dns-api/keytabs/…​: permission denied

Неверные права доступа к keytab-файлам или TLS-ключу

Выполнить:
sudo chown dnsel:dnsel /etc/elles-dns-api/keytabs/*
и
sudo chmod 600 /etc/elles-dns-api/keytabs/*.keytab /etc/elles-dns-api/keytabs/api-server.key

krb5.conf file is not accessible (permission denied) at /usr/local/samba/private/krb5.conf

Сгенерированная конфигурация указывает на внутренний файл krb5.conf «Эллес», который не доступен пользователю dnsel

Убедитесь что /etc/krb5.conf существует и доступен для чтения, затем запустите скрипт с флагом --force для повторной генерации конфигурации:
sudo elles-dns-api-setup --force

tls: failed to find any PEM data

TLS-сертификат или ключ отсутствуют, повреждены или указан неверный путь

Проверить существование файлов api-server.crt и api-server.key в /etc/elles-dns-api/keytabs/ и убедиться, что они доступны пользователю dnsel для чтения

spnego: keytab not found

Keytab-файл для SPNEGO отсутствует в ожидаемом каталоге

Запустить скрипт elles-dns-api-setup на контроллере домена и скопировать файл spnego-svc.keytab в /etc/elles-dns-api/keytabs/ (если на отдельном хосте)

GSSAPI bind failed

Keytab для LDAP не содержит корректные ключи или SPN не настроен

Повторно сгенерировать keytab на контроллере домена:
elles-dns-api-setup --force (идемпотентно)

config.yaml: no such file

Конфигурационный файл отсутствует

Запустить sudo elles-dns-api-setup на контроллере домена для автоматической генерации файла конфигурации

config validation failed

Конфигурация невалидна

Запустить валидацию:
sudo elles-dns-api config validate --config /etc/elles-dns-api/config.yaml
Исправить указанные поля

port 9443 already in use

Порт занят другим процессом

Найти процесс:
sudo ss -tlnp | grep 9443
Остановить его или изменить порт в config.yaml

Сервис не запускается: в логе отсутствует сообщение GSSAPI bind SUCCESS

Если в лог-файле нет строки "GSSAPI bind SUCCESS", это указывает на проблему с аутентификацией LDAP.

Проверьте, что keytab-файл доступен пользователю dnsel для чтения:

sudo -u dnsel klist -kt /etc/elles-dns-api/keytabs/ldap-svc.keytab

Если вывод пуст, keytab поврежден, не экспортирован или не содержит нужных ключей.

Сформируйте keytab-файл повторно на контроллере домена:

sudo elles-dns-api-setup --force

API возвращает 401 Unauthorized: клиент не смог пройти Kerberos-аутентификацию

Сервер не может аутентифицировать клиента через Kerberos/SPNEGO.

Выполните проверки на стороне клиента:

  • получите билет Kerberos:

    kinit user@<REALM>

  • проверьте наличие билета:

    klist

  • проверьте разрешение FQDN сервера REST API:

    nslookup <api-fqdn>

  • проверьте синхронизацию времени (Kerberos требует расхождения <5 минут):

    sudo ntpdate -u <dc-fqdn>

<dc-fqdn> в проверках — FQDN целевого контроллера домена; <api-fqdn> — FQDN хоста, на котором развернут сервер elles-dns-api.

API возвращает 401 Unauthorized: SPN настроен некорректно

На контроллере домена проверьте SPN для учетной записи svc-dnsel-http:

sudo /app/inno-samba/bin/samba-tool spn list svc-dnsel-http

Ожидаемый результат: HTTP/<api-fqdn>@<REALM>.

<api-fqdn> — FQDN хоста, на котором развернут сервер elles-dns-api.

Клиент должен обращаться к REST API строго по FQDN, указанному в SPN. Использование IP-адреса, короткого имени или другого DNS-имени приведет к отказу в аутентификации.

API возвращает 403 Forbidden: пользователь аутентифицирован, но отсутствуют права

Проверьте корректность сопоставления для RBAC в config.yaml:

rbac:
  group_roles:
    S-1-5-21-...-1101:    # SID DNSAdmins (определен автоматически)
      - role_dns_admins
  user_roles:
    S-1-5-21-...-1107:    # супер-администратор (нужно раскомментировать)
      - role_super_admin

Получить SID текущего пользователя на контроллере домена:

sudo /app/inno-samba/bin/samba-tool user show <username> |grep -i objectSid

Добавьте SID в user_roles и перезапустите сервис:

sudo systemctl restart elles-dns-api.service

Ошибка проверки ACL: операция записи от имени пользователя без членства в DnsAdmins

Если RBAC-политика сервиса разрешает операцию, но служба каталогов отклоняет ее на уровне ACL, возникает ошибка:

{
  "error": "failed to create zone",
  "code": 403,
  "source": "ldap",
  "name": "LDAP_INSUFFICIENT_ACCESS_RIGHTS"
}

Это не ошибка конфигурации, а корректное поведение системы.

«Эллес» использует механизм делегирования S4U2Proxy, при котором права доступа к объектам проверяются не относительно служебной учетной записи (svc-dnsel-ldap), а относительно реального пользователя, от имени которого выполнен запрос (то еть конечного клиента).

Добавьте пользователя в группу DnsAdmins на контроллере домена:

sudo /app/inno-samba/bin/samba-tool group addmembers DnsAdmins <username>

Ошибка сертификата при использовании curl (SSL certificate problem)

При попытке обратиться к API-сервису по HTTPS (например, через curl) может возникнуть ошибка сертификата, если CA-сертификаты не установлены в системное хранилище (trust store).

Для устранения ошибки запустите скрипт настройки с флагом --force, чтобы гарантированно установить все необходимые CA-сертификаты в системное хранилище:

sudo elles-dns-api-setup --force

Проверьте, что сертификаты установлены:

ls -la /usr/local/share/ca-certificates/elles-*.crt
ls -la /etc/ssl/certs/elles-*.pem

Скрипт elles-dns-api-setup не находит «Эллес»

Укажите путь явно:

sudo elles-dns-api-setup --samba-dir /app/inno-samba

Проверьте, что «Эллес» развернут:

ls /app/inno-samba/private/sam.ldb

Custom partitions summary count=0

Данное поведение является штатным, если:

  1. Партиция не реплицирована на контроллер домена и запрос к /api/v1/dns/partitions возвращает available: false.

  2. Партиция еще не создана.

Для проверки выполните:

curl -k --negotiate -u : \
  "https://<api-fqdn>:9443/api/v1/dns/partitions" | jq '.partitions[] |select(.kind=="custom")'

Если available: false, см. причину в поле unavailable_reason.

Обновлено: