Настройка elles-dns-api с использованием конфигурационного файла

При необходимости изменения конфигурации elles-dns-api отредактируйте файл config.yaml на хосте, где развернут сервер (путь к файлу после установки — /etc/elles-dns-api/config.yaml), и выполните перезапуск сервиса:

sudo systemctl restart elles-dns-api.service

При создании или редактировании файла config.yaml учитывайте следующее:

  • формат YAML предъявляет строгие требования к форматированию (см. RFC 9512), поэтому тщательно соблюдайте отступы;

  • все параметры можно переопределить переменными окружения в формате DNSEL_<SECTION>_<PARAM>;

  • ключевые файлы (*.keytab, api-server.key) должны иметь права доступа 600 и принадлежать пользователю dnsel;

  • если используется HTTPS, то в условиях штатной эксплуатации TLS-сертификат должен быть выдан доверенным центром сертификации (CA).

Формат config.yaml

log_level: "info"

server:
  host: "0.0.0.0"
  port: 9443
  read_timeout: 30s
  write_timeout: 30s
  idle_timeout: 120s

tls:
  cert_file: "/etc/elles-dns-api/keytabs/api-server.crt"
  key_file: "/etc/elles-dns-api/keytabs/api-server.key"

spnego:
  spn: "HTTP/dc1.example.com"
  keytab_path: "/etc/elles-dns-api/keytabs/spnego-svc.keytab"
  realm: "EXAMPLE.COM"
  kdcs:
    - "dc1.example.com:88"

ldap:
  url: "ldap://dc1.example.com:389"
  realm: "EXAMPLE.COM"
  base_dn: "DC=example,DC=com"
  username: "svc-dnsel-ldap"
  spn: "ldap/dc1.example.com"
  keytab: "/etc/elles-dns-api/keytabs/ldap-svc.keytab"
  krb5_config: "/etc/krb5.conf"
  cache_ttl: 10m
  delegation:
    enabled: true
    timeout: 5s

casbin:
  model_path: "/etc/elles-dns-api/rbac_model.conf"
  policy_path: "/etc/elles-dns-api/policy.csv"

dns:
  zones_container: ""
  default_record_ttl: 3600s
  defaults:
    ns_hostname: "dc1.example.com"
    responsible_party: "hostmaster.example.com"
    default_ttl: 3600
    delegation:
      external_ns_timeout: 5s

dns_rpc:
  server: "dc1.example.com"
  realm: "EXAMPLE.COM"
  username: "svc-dnsel-rpc"
  keytab: "/etc/elles-dns-api/keytabs/dnsrpc-svc.keytab"
  timeout: 15s

rate_limit:
  requests_per_second: 100

cors:
  allowed_origins: ["*"]
  allow_credentials: false
  allowed_methods: ["GET", "POST", "PUT", "DELETE", "PATCH", "OPTIONS"]
  allowed_headers: ["Authorization", "Content-Type"]

rbac:
  group_roles:
    S-1-5-21-3633072393-148695822-1854736953-1101:
      - role_dns_admins
  user_roles:
    S-1-5-21-3633072393-148695822-1854736953-1107:
      - role_super_admin

Параметры config.yaml

Конфигурация состоит из секций:

Секция Назначение

log_level

Глобальный уровень логирования

server

HTTP-сервер (адрес, порт, таймауты)

tls

TLS-сертификаты для HTTPS

spnego

Kerberos SPNEGO аутентификация клиентов

ldap

Подключение к Active Directory (с Kerberos)

casbin

RBAC-модели и политики

dns

Параметры по умолчанию для DNS-операций

dns_rpc

RPC-клиент для DNS Server Management Protocol

rate_limit

Ограничение запросов в секунду

cors

Cross-Origin Resource Sharing

rbac

Сопоставление SID групп/пользователей с ролями

Секция log_level

Глобальный уровень логирования.

log_level

Уровень детализации логов.

Доступные значения:

  • debug — максимальная детализация (включая LDAP-запросы и Kerberos-обмен);

  • info — основные события (по умолчанию для штатной эксплуатации);

  • warn — только предупреждения;

  • error — только ошибки.

Секция server

Параметры HTTP-сервера.

host

IP-адрес сервера.

Значение по умолчанию: 0.0.0.0.

port

Порт для HTTPS-подключения к API.

Значение по умолчанию: 9443.

read_timeout

Время ожидания чтения HTTP-запроса (в формате duration: 30s, 1m).

Значение по умолчанию: 30s.

write_timeout

Время ожидания записи HTTP-ответа (в формате duration).

Значение по умолчанию: 30s.

idle_timeout

Время ожидания неактивного соединения (keep-alive) (в формате duration).

Значение по умолчанию: 120s.

Секция tls

Параметры TLS-сертификата для HTTPS.

cert_file

Обязательно. Путь к файлу TLS-сертификата в формате PEM.

key_file

Обязательно. Путь к приватному ключу TLS-сертификата в формате PEM.

Сертификат должен быть выдан доверенным центром сертификации для штатной эксплуатации. Самоподписанные сертификаты допустимы только в тестовых средах.

Секция spnego

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

spn

Обязательно. Service Principal Name (SPN) для HTTP-сервиса.

Формат: HTTP/<api-fqdn> (например, HTTP/api-host.example.com).

Значение должно совпадать с SPN, созданным скриптом elles-dns-api-setup.

keytab_path

Обязательно. Путь к keytab-файлу, содержащему ключи для указанного SPN.

realm

Обязательно. Kerberos-область (Realm), к которой принадлежит SPN.

Должна совпадать с Realm контроллера домена (например, EXAMPLE.COM).

kdcs

Список KDC-серверов в формате hostname:port.

Если не указано, используется DNS SRV-запись или /etc/krb5.conf.

Пример:

kdcs:
  - "dc1.example.com:88"
  - "dc2.example.com:88"

Секция ldap

Параметры подключения к Active Directory через LDAP с GSSAPI-аутентификацией.

url

Обязательно. URL LDAP-сервера. Должен начинаться с ldap:// (автоматически используется STARTTLS) или ldaps:// (TLS сразу).

Пример: ldap://dc.example.com:389

realm

Обязательно. Kerberos-область для GSSAPI-аутентификации. Должна совпадать со значением spnego.realm.

base_dn

Базовый DN для поиска DNS-зон и записей в Active Directory.

Пример: DC=example,DC=com

username

Имя служебной учетной записи для GSSAPI-аутентификации.

По умолчанию: svc-dnsel-ldap

spn

SPN LDAP-сервиса контроллера домена.

Формат: ldap/<dc-fqdn> (например, ldap/dc.example.com).

keytab

Обязательно. Путь к keytab-файлу для GSSAPI-аутентификации LDAP.

krb5_config

Путь к файлу krb5.conf для настройки клиента Kerberos.

Если не указан, используется системный файл /etc/krb5.conf.

cache_ttl

Время жизни кэша LDAP-соединений (в формате duration).

Значение по умолчанию: 10m

delegation.enabled

Обязательно. Включает поддержку делегирования зон через API.

Значение по умолчанию: true.

delegation.timeout

Время ожидания операций делегирования (в формате duration).

Значение по умолчанию: 5s.

Секция casbin

Параметры RBAC-модели Casbin.

model_path

Обязательно. Путь к файлу модели Casbin (rbac_model.conf).

policy_path

Обязательно. Путь к файлу политики Casbin (policy.csv).

Секция dns

Параметры по умолчанию для DNS-операций.

zones_container

DN контейнера DNS-зон в Active Directory.

Если не указан, автоматически определяется из RootDSE.

default_record_ttl

Срок действия по умолчанию для новых DNS-записей (в секундах).

Значение по умолчанию: 3600s

Подсекция defaults

Параметры по умолчанию для создания DNS-зон через API.

ns_hostname

FQDN авторитетного DNS-сервера для SOA.PrimaryServer и NS-записей.

Если не задан, используется dnsHostName из RootDSE.

responsible_party

Email администратора зоны в DNS-формате (точка вместо @).

Если не задан, используется hostmaster.<zone_name>.

default_ttl

TTL по умолчанию для SOA.MinimumTTL и SOA/NS-записей (в секундах).

Значение по умолчанию: 3600.

Подсекция defaults.delegation

Параметры делегирования DNS-зон.

external_ns_timeout

Время ожидания проверки внешних NS-серверов через SOA-запрос (в формате duration).

Значение по умолчанию: 5s.

Секция dns_rpc

Параметры подключения к DNS Server Management Protocol (DCE/RPC).

server

Обязательно. FQDN DNS-сервера, к которому подключается RPC.

Пример: dc.example.com

realm

Обязательно. Kerberos-область для RPC-аутентификации.

Должна совпадать со значением spnego.realm.

username

Имя служебной учетной записи для аутентификации в RPC.

По умолчанию: svc-dnsel-rpc

keytab

Обязательно. Путь к keytab-файлу для аутентификации DCE/RPC.

timeout

Время ожидания выполнения RPC-запроса (в формате duration).

Значение по умолчанию: 15s

Секция rate_limit

Ограничение количества запросов в секунду.

requests_per_second

Максимальное количество запросов в секунду на один IP-адрес (алгоритм token bucket).

Значение по умолчанию: 100

Секция cors

Параметры Cross-Origin Resource Sharing.

allowed_origins

Список разрешенных источников (origins) для CORS.

Пример: ["https://ui.example.com", "https://admin.example.com"]

Значение "*" разрешает все источники — не рекомендуется в условиях штатной эксплуатации.

allow_credentials

Разрешает отправку учетных данных (cookies, заголовки авторизации).

Значение true несовместимо с allowed_origins: ["*"].

allowed_methods

Список разрешенных HTTP-методов.

Значение по умолчанию: ["GET", "POST", "PUT", "DELETE", "PATCH", "OPTIONS"]

allowed_headers

Список разрешенных HTTP-заголовков.

Значение по умолчанию: ["Authorization", "Content-Type"]

Секция rbac

Сопоставление SID групп и пользователей Active Directory с ролями Casbin.

Формат SID:

S-1-5-21-<domain>-<sub-auth>-<sub-auth>-<RID>

Как узнать SID группы:

  • с помощью PowerShell на Windows Server:

    Get-ADGroup "DNS Admins" | Select-Object -ExpandProperty SID

  • с помощью ldapsearch на Linux:

    ldapsearch -H ldap://dc.example.com -b "DC=example,DC=com" \
"(sAMAccountName=DNS Admins)" objectSid
group_roles

Сопоставление SID групп с ролями.

Формат: SID: [role1, role2]

user_roles

Сопоставление SID пользователей с ролями (опционально).

Формат: SID: [role1, role2]

Встроенные роли:

  • role_super_admin — полный доступ;

  • role_dns_admins — управление DNS;

  • role_reader — только чтение.

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

Все параметры в конфигурации можно переопределить переменными окружения в формате DNSEL_<SECTION>_<PARAM> (верхний регистр, точки заменены _):

Переменная Соответствие

DNSEL_LOG_LEVEL

log_level

DNSEL_SERVER_HOST

server.host

DNSEL_SERVER_PORT

server.port

DNSEL_TLS_CERT_FILE

tls.cert_file

DNSEL_TLS_KEY_FILE

tls.key_file

DNSEL_SPNEGO_KEYTAB_PATH

spnego.keytab_path

DNSEL_LDAP_URL

ldap.url

DNSEL_LDAP_KEYTAB

ldap.keytab

DNSEL_LDAP_DELEGATION_ENABLED

ldap.delegation.enabled

DNSEL_LDAP_DELEGATION_TIMEOUT

ldap.delegation.timeout

DNSEL_DNS_DEFAULTS_EXTERNAL_NS_TIMEOUT

dns.defaults.delegation.external_ns_timeout

DNSEL_DNS_RPC_KEYTAB

dns_rpc.keytab

Переменные окружения имеют приоритет над значениями в YAML.

Проверка конфигурации

После настройки файла config.yaml необходимо проверить его корректность.

Валидация синтаксиса

Проверьте синтаксис с помощью встроенной команды, указав путь к файлу в ключе --config:

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

Если вывод отсутствует, синтаксис корректный. Если возникает ошибка, проверьте отступы, кавычки и структуру YAML в соответствии с RFC 9512.

Проверка при старте сервера

При запуске сервиса elles-dns-api в логах отображаются ключевые события, подтверждающие успешную инициализацию компонентов.

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

sudo journalctl -u elles-dns-api -f

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

{"msg":"ldap config","url":"ldap://dc.example.com:389"}
{"msg":"StartTLS established"}
{"msg":"GSSAPI bind SUCCESS"}
{"msg":"RootDSE discovered","default_nc":"DC=example,DC=com"}
{"msg":"DNS context discovered","domain_container":"CN=MicrosoftDNS,DC=DomainDnsZones,DC=example,DC=com"}
{"msg":"Custom partitions summary","count":0}

Интерпретация сообщений:

  • StartTLS established — успешно установлено защищенное LDAP-соединение;

  • GSSAPI bind SUCCESS — аутентификация через Kerberos прошла без ошибок;

  • RootDSE discovered — сервер получил информацию о домене;

  • DNS context discovered — найден контейнер DNS-зон в Active Directory;

  • Custom partitions summary — количество пользовательских DNS-зон (если 0, то это штатная ситуация).

Безопасность

Для обеспечения безопасности при работе с elles-dns-api выполните обязательные требования и следуйте рекомендациям.

Обязательные требования

Обязательные требования включают:

  1. Все keytab-файлы должны иметь права 600 и принадлежать пользователю dnsel:

    ls -l /etc/elles-dns-api/keytabs/*.keytab
# -rw------- dnsel dnsel spnego-svc.keytab
# -rw------- dnsel dnsel ldap-svc.keytab
# -rw------- dnsel dnsel dnsrpc-svc.keytab

  2. В условиях штатной эксплуатации не используйте самоподписанные сертификаты. Используйте сертификаты, выданные корпоративным или публичным центром сертификации (CA).

  3. В условиях штатной эксплуатации запрещайте доступ из произвольных источников:

       cors:
     allowed_origins: ["https://ui.example.com", "https://admin.example.com"]
     allow_credentials: true

  4. Ограничьте количество запросов для защиты от DDoS-атак:

       rate_limit:
     requests_per_second: 100

Рекомендации

При эксплуатации elles-dns-api следуйте рекомендациям:

  1. Не сохраняйте config.yaml с реальными путями к keytab-файлам в системы контроля версий. Используйте шаблон config.example.yaml для репозитория.

  2. Используйте переменные окружения для секретов:

      export DNSEL_SPNEGO_KEYTAB_PATH="/run/secrets/spnego.keytab"
  export DNSEL_LDAP_KEYTAB="/run/secrets/ldap.keytab"
  export DNSEL_DNS_RPC_KEYTAB="/run/secrets/dnsrpc.keytab"
  sudo systemctl restart elles-dns-api.service

  3. Используйте отдельную учетную запись для каждого компонента:

    • svc-dnsel-ldap — только чтение данных из Active Directory (минимальные права);

    • svc-dnsel-rpc — только операции DCE/RPC (не имеет доступа к LDAP);

    • svc-dnsel-http — только аутентификация HTTP (не имеет прав на изменение данных).

Все keytab-файлы и TLS-ключи должны храниться только на хосте с развернутым сервером elles-dns-api и никогда не передаваться клиентам.

Обновлено: