Управление Avanpost DS из терминала. Утилита DSAPI

Навигатор по разделу:

1. Общая информация

Утилита "dsapi" используется для управления доменным разделом каталога Avanpost DS через REST API. Запускается в терминале на контроллерах домена и компьютерах в домене Avanpost DS.
Для использования утилиты на компьютере в домене Avanpost DS требуется переместить утилиту "/opt/avanpost/tools/dsapi/dsapi" с контроллера домена на компьютер.

2. Параметры утилиты "dsapi"

ВНИМАНИЕ:

Перед использованием команд необходимо подключится к КД (создать сессию) с помощью параметра "connect-server".

ПараметрОписаниеКлючи

./dsapi connect-server


Подключение к серверу и создание сессии.

Метод: POST /api/v1/login

КлючЗначение
--domainДомен для поиска контроллера домена по SRV-записи
--serverАдрес контроллера домена. Если не указан, определяется по ключу "--domain".
Адрес не должен начинаться с протокола (http:// или https://). Для выбора протокола необходимо использовать ключ "--usessl"
--loginОбязательный ключ. Логин для входа
--password Пароль. Если не указан, будет запрошен интерактивно
--portПорт (по умолчанию 443)
--usesslФлаг включения SSL. С помощью данного флага доступна смена протокола (http:// или https://). По умолчанию значение "true" (https://)
--trust-all-certificatesДоверять всем TLS-сертификатам (включая самоподписанным и недействительным, это небезопасно). По умолчанию значение "false" (доверие выключено)

Внимание! Флаги --usessl и --trust-all-certificates логического типа (принимают значения "true" или "false").

В отличие от других ключей, флаги задаются через знак равно: "--usessl=true" или "--usessl=false".

Примеры использования:

Подключение через домен
# Поиск КД через домен example.com и подключение по HTTP и порту 83
./dsapi connect-server --domain example.com --login Administrator --password Avanp0st --port 80 --usessl=false
Подключение напрямую
# Подключение напрямую по HTTP и порту 83
./dsapi connect-server --server ds01.example.com --login Administrator --password Avanp0st --port 80 --usessl=false

./dsapi invoke-method


Выполнение произвольного HTTP‑запроса к REST API.

Результат:
Тело ответа форматируется как JSON (с отступами).
При пустом ответе выводится сообщение: "Ответ пустой".

КлючЗначение
--method

Обязательный ключ. Путь метода, например: "/api/v1/groups"

--typeОбязательный ключ. HTTP‑метод: GETPOSTPUTPATCHDELETE и др.
--attributes

Тело HTTP‑запроса. Внимание! Тело запроса требуется указывать в одинарных кавычках.
Если тело запроса большое и возникают проблемы в терминале, следует использовать ключ "--file"

--file

Путь к файлу с телом HTTP‑запроса. Внимание! Нельзя одновременно использовать ключи "--attributes" и "--file"

Примеры использования:

Получение списка пользователей
./dsapi invoke-method --method "/api/v1/users?cookie=&pageSize=10" --type GET
Получение списка пользователей, начинающихся на "Audit"
./dsapi invoke-method --method "/api/v1/users?cookie=&pageSize=10&search=Audit" --type GET
Получение подразделения "ou=hosts" (с указанием тела запроса напрямую)
./dsapi invoke-method --method "/api/v1/hierarchy" --type POST --attributes '{"baseObject":"ou=hosts,dc=example,dc=com",
"filter":{"mode":"ou","mask":"","sizeLimit":1001},"attributes":["description","objectclass","cn","uid","dn","ou"]}'
Получение подразделения "ou=hosts" (с указанием тела запроса в файле)
./dsapi invoke-method --method "/api/v1/hierarchy" --type POST --file "/home/ads/input.json"

Управление пользователями

./dsapi add-user

Создание нового пользователя.

Метод: POST /api/v1/users

Результат:
Пользователь создан, выводится сообщение об успехе, запрашиваются и выводятся актуальные данные.

КлючЗначение

--cn

Обязательный ключ. Общее имя объекта.

Разрешено использовать только латинские буквы, цифры, точку, дефис "-", символ подчеркивания "_".

--passwordОбязательный ключ. Пароль пользователя
--givennameИмя
--surnameФамилия
--mailАдрес электронной почты
--photoПуть/идентификатор фото
--mobileМобильный телефон
--requirepasswordchangeФлаг для включения требования смены пароля при следующем входе пользователя
--passwordneverexpiresФлаг для отключения срока жизни пароля. При значении "true" срок жизни пароля никогда не истекает. По умолчанию значение "true"
--samaccountnameИмя входа Windows
--parent
DN родительского объекта

Из ключей "--parent" и "--cn" собирается полный DN нового объекта.
Объект создаётся внутри родительского объекта с DN, указанным в ключе "--parent".

--formatФормат вывода. По умолчанию используется формат JSON. Другие форматы могут быть добавлены при необходимости.
Пример использования
./dsapi add-user --cn lipov --password Avanp0st

./dsapi get-user

Получение информации о пользователе.

Метод: GET /api/v1/users/{uid}

Результат:
Выводятся актуальные данные пользователя.
При отсутствии записи выводится сообщение: "Запись отсутствует".

КлючЗначение
--identityОбязательный ключ. Идентификатор: CNDN или UID.
--formatФормат вывода. По умолчанию используется формат JSON. Другие форматы могут быть добавлены при необходимости.
Пример использования
./dsapi get-user --identity "cn=lipov,ou=users,dc=example,dc=com"

./dsapi get-users

Получение списка пользователей.

Метод: GET /api/v1/users/

Результат:
Выводится список пользователей, соответствующих заданным параметрам.

КлючЗначение
--indexИндекс первой записи (смещение). Значение по умолчанию: 0
--sizeОбязательный ключ. Количество записей на странице. Значение должно быть выше 0
--filterФильтр по CN. Будут выведены только объекты, имя которых начинается значением, указанным в фильтре.
--parentDN родительского объекта
--formatФормат вывода. По умолчанию используется формат JSON. Другие форматы могут быть добавлены при необходимости.
Пример использования
./dsapi get-users --size 10 --parent "cn=All Users,ou=groups,dc=example,dc=com"

./dsapi modify-user

Изменение атрибутов пользователя.

Метод: PUT /api/v1/users/{uid}

Результат:
Атрибуты пользователя изменены, выводится сообщение об успехе, запрашиваются и выводятся актуальные данные.
При отсутствии записи выводится сообщение: "Запись отсутствует".

КлючЗначение
--identityОбязательный ключ. Идентификатор изменяемого пользователя: CNDN или UID.
--formatФормат вывода. По умолчанию используется формат JSON. Другие форматы могут быть добавлены при необходимости.

Атрибуты для изменения

--cn

Общее имя объекта

--name

Имя
--displaynameОтображаемое имя

--givenname

Имя

--surname

Фамилия

--middlename

Отчество

--initials

Инициалы

--gn

Заданное имя (given name)

--sn

Фамилия (surname)

--gecos

GECOS-информация (комментарий)

--samaccountname

Имя входа Windows

--gidnumber

GID группы

--homedirectory

Домашний каталог

--loginshell

Логин-шелл

--photo

Путь/идентификатор фото

--employeenumber

Номер сотрудника

Контактные данные

--mail

Адрес электронной почты

--rfc822mailbox

Адрес электронной почты (RFC822)

--proxyaddresses

Прокси-адреса

--mobile

Мобильный телефон

--mobiletelephonenumber

Мобильный телефон

--telephonenumber

Телефон

--homephone

Домашний телефон

--hometelephonenumber

Домашний телефон

--facsimiletelephonenumber

Факс

--fax

Факс (сокращённо)

--pager

Пейджер

--pagertelephonenumber

Номер пейджера

--internationalisdnnumber

Международный ISDN-номер

--labeleduri

Метка URI

--x121address

X.121 адрес

--telexnumber

Номер телетекс

--teletexterminalidentity

Идентификатор телетекс-терминала

Организационная информация

--company

Компания

--o

Название организации

--organizationname

Название организации (полное)

--organizationalunitname

Организационное подразделение (полное)

--department

Отдел

--departmentnumber

Номер отдела

--division

Подразделение

--title

Должность

--manager

Руководитель

--secretary

Секретарь

--employeetype

Тип сотрудника

--businesscategory

Категория бизнеса

--roomnumber

Номер комнаты

--physicaldeliveryofficename

Офис доставки

Адрес и местоположение

--postaladdress

Почтовый адрес

--homepostaladdress

Домашний почтовый адрес

--registeredaddress

Зарегистрированный адрес

--street

Улица

--streetaddress

Адрес улицы

--postofficebox

Почтовый ящик

--postalcode

Почтовый индекс

--l

Населенный пункт

--localityname

Населенный пункт (полностью)

--st

Регион

--stateorprovincename

Название провинции
--destinationindicatorИндикатор назначения

--preferreddeliverymethod

Предпочтительный способ доставки

Безопасность и пароль

--accountexpires

Срок действия учётной записи

--logonhours

Часы входа в систему

--passwordneverexpires

Флаг для отключения срока жизни пароля. При значении "true" срок жизни пароля никогда не истекает. По умолчанию значение "true"

--requirepasswordchange

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

Прочее

--description

Описание

--carlicense

Номер водительского удостоверения

--preferredlanguage

Предпочитаемый язык

--seealso

Ссылка на связанные объекты

--x500uniqueidentity

Уникальный идентификатор X.500
Пример использования
./dsapi modify-user --identity "cn=lipov,ou=users,dc=example,dc=com" --mail "lipov@avanpost.ru"

Внимание! При использовании команды должен быть указан один или более атрибутов для изменения.

./dsapi delete-user

Удаление пользователя.

Метод: DELETE /api/v1/users/{uid}

Результат:
Выводится сообщение об успешном удалении.
При отсутствии записи выводится сообщение: "Запись отсутствует".

КлючЗначение
--identityОбязательный ключ. Идентификатор удаляемого пользователя: CNDN или UID.
Пример использования
./dsapi delete-user --identity "cn=lipov,ou=users,dc=example,dc=com"

Управление группами

./dsapi add-group

Создание новой группы.

Метод: POST /api/v1/groups

Результат: 
Группа создана, выводится сообщение об успехе, запрашиваются и выводятся актуальные данные.

КлючЗначение

--cn

Обязательный ключ. Общее имя объекта

--description

Описание
--parent
DN родительского объекта

Из ключей "--parent" и "--cn" собирается полный DN нового объекта.
Объект создаётся внутри родительского объекта с DN, указанным в ключе "--parent".

--formatФормат вывода. По умолчанию используется формат JSON. Другие форматы могут быть добавлены при необходимости.
Пример использования
./dsapi add-group --cn "new_group" --parent "cn=All Users,ou=groups,dc=example,dc=com"

./dsapi get-group

Получение информации о группе.

Метод: GET /api/v1/groups/{uid}

Результат:
Выводятся актуальные данные группы.
При отсутствии записи выводится сообщение: "Запись отсутствует".

КлючЗначение
--identityОбязательный ключ. Идентификатор группы: CNDN или UID.
--formatФормат вывода. По умолчанию используется формат JSON. Другие форматы могут быть добавлены при необходимости.
Пример использования
./dsapi get-group --identity "cn=All Users,ou=groups,dc=example,dc=com"

./dsapi get-groups

Получение списка групп.

Метод: GET /api/v1/groups/

Результат: 
Выводится список групп, соответствующих заданным параметрам.

КлючЗначение
--indexИндекс первой записи (смещение). Значение по умолчанию: 0
--sizeОбязательный ключ. Количество записей на странице. Значение должно быть выше 0
--filterФильтр по CN. Будут выведены только объекты, имя которых начинается значением, указанным в фильтре.
--formatФормат вывода. По умолчанию используется формат JSON. Другие форматы могут быть добавлены при необходимости.
Пример использования
./dsapi get-groups --size 10 --filter "DNS"

./dsapi modify-group

Изменение атрибутов группы.

Метод: PUT /api/v1/groups/{uid}

Результат: 
Группа изменена, выводится сообщение об успехе, запрашиваются и выводятся актуальные данные.
При отсутствии записи выводится сообщение: "Запись отсутствует".

КлючЗначение
--identityОбязательный ключ. Идентификатор группы: CNDN или UID.
--formatФормат вывода. По умолчанию используется формат JSON. Другие форматы могут быть добавлены при необходимости.

Атрибуты для изменения

--cn

Общее имя объекта

--description

Описание

--gidnumber

GID

--objectcategory

Категория объекта
--samaccountnameИмя входа Windows

--mail

Адрес электронной почты

--rfc822mailbox

Адрес электронной почты (RFC822)
Пример использования
./dsapi modify-group --identity "cn=new_group,ou=groups,dc=example,dc=com" --cn "old_group"

Внимание! При использовании команды должен быть указан один или более атрибутов для изменения.

./dsapi delete-group

Удаление группы.

Метод: DELETE /api/v1/groups/{uid}

Результат: 
Выводится сообщение об успешном удалении.
При отсутствии записи выводится сообщение: "Запись отсутствует".

 

КлючЗначение
--identityОбязательный ключ. Идентификатор удалямой группы: CNDN или UID.
Пример использования
./dsapi delete-group --identity "cn=new_group,ou=groups,dc=example,dc=com"

./dsapi add-group-members

Добавление участников в группу.

Метод: PUT /api/v1/groups/{uid}/members-add-uids

Результат: 
Участники добавлены, выводится сообщение об успехе.
При отсутствии группы выводится сообщение: "Запись отсутствует".
Если один из участников не существует, выводится соответствующая ошибка.

КлючЗначение
--identityОбязательный ключ. Идентификатор группы: CNDN или UID.

--members

Обязательный ключ. Участники группы: CNDN или UID, разделяемые запятой. DN указывается в кавычках.

Внимание! При перечислении CN участников могут возникнуть ошибки, если существуют группа/компьютер/пользователь с одинаковым CN.
В таком случае будет использован первый найденный объект при поиске в следующей последовательности: 1 – группы, 2 – компьютеры, 3 – пользователи.

Пример использования
./dsapi add-group-members --identity "cn=new_group,ou=groups,dc=example,dc=com" --members 'user1,"cn=user2,ou=users,dc=example,dc=com",8d5551a3-41c5-49ea-8d7f-81aa97c875a1'

./dsapi get-group-members

Получение списка участников группы.

Метод: GET /api/v1/groups/{uid}/members

Результат: 
Выводится список участников группы, соответствующий заданным параметрам.

КлючЗначение
--identityОбязательный ключ. Идентификатор группы: CNDN или UID.
--indexИндекс первой записи (смещение). Значение по умолчанию: 0
--sizeОбязательный ключ. Количество записей на странице. Значение должно быть выше 0
--filterФильтр по CN. Будут выведены только объекты, имя которых начинается значением, указанным в фильтре.
--formatФормат вывода. По умолчанию используется формат JSON. Другие форматы могут быть добавлены при необходимости.
Пример использования
./dsapi get-group-members --identity "cn=new_group,ou=groups,dc=example,dc=com" --size 10 --filter "admin"

./dsapi delete-group-members

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

Метод: PUT /api/v1/groups/{uid}/members-remove-uids

Результат: 
Выводится сообщение об успешном удалении.
При отсутствии группы выводится сообщение: "Запись отсутствует".
Если один из участников не существует, выводится соответствующая ошибка.

КлючЗначение
--identityОбязательный ключ. Идентификатор группы: CNDN или UID.

--members

Обязательный ключ. Участники группы: CNDN или UID, разделяемые запятой. DN указывается в кавычках.

Внимание! При перечислении CN участников могут возникнуть ошибки, если существуют группа/компьютер/пользователь с одинаковым CN.
В таком случае будет использован первый найденный объект при поиске в следующей последовательности: 1 – группы, 2 – компьютеры, 3 – пользователи.

Пример использования
./dsapi delete-group-members --identity "cn=new_group,ou=groups,dc=example,dc=com" --members 'user1,"cn=user2,ou=users,dc=example,dc=com",8d5551a3-41c5-49ea-8d7f-81aa97c875a1'

Управление компьютерами

./dsapi add-host

Создание нового компьютера.

Метод: POST /api/v1/hosts

Результат: 
Компьютер создан, выводится сообщение об успехе, запрашиваются и выводятся актуальные данные.

КлючЗначение

--cn

Обязательный ключ. Общее имя компьютера

Разрешено использовать только буквы, цифры и символ: -

--description

Описание
--samaccountnameИмя входа Windows
--parent
DN родительского объекта

Из ключей "--parent" и "--cn" собирается полный DN нового объекта.
Объект создаётся внутри родительского объекта с DN, указанным в ключе "--parent".

--formatФормат вывода. По умолчанию используется формат JSON. Другие форматы могут быть добавлены при необходимости.
Пример использования
./dsapi add-host --cn "t-ds-twads01" --parent "cn=new_group,ou=groups,dc=example,dc=com"

./dsapi get-host

Получение информации о компьютере.

Метод: GET /api/v1/hosts/{uid}

Результат:
Выводятся актуальные данные компьютера.
При отсутствии записи выводится сообщение: "Запись отсутствует".

КлючЗначение
--identityОбязательный ключ. Идентификатор компьютера: CNDN или UID.
--formatФормат вывода. По умолчанию используется формат JSON. Другие форматы могут быть добавлены при необходимости.
Пример использования
./dsapi get-host --identity "cn=t-ds-twads01,ou=domaincontrollers,dc=example,dc=com"

./dsapi get-hosts

Получение списка компьютеров.

Метод: GET /api/v1/hosts/

Результат:
Выводится список компьютеров, соответствующих заданным параметрам.

КлючЗначение
--indexИндекс первой записи (смещение). Значение по умолчанию: 0
--sizeОбязательный ключ. Количество записей на странице. Значение должно быть выше 0
--filterФильтр по CN. Будут выведены только объекты, имя которых начинается значением, указанным в фильтре.
--formatФормат вывода. По умолчанию используется формат JSON. Другие форматы могут быть добавлены при необходимости.
Пример использования
./dsapi get-hosts --size 10 --filter "t-ds"

./dsapi modify-host

Изменение атрибутов компьютера.

Метод: PUT /api/v1/hosts/{uid}

Результат:
Компьютер изменен, выводится сообщение об успехе, запрашиваются и выводятся актуальные данные.
При отсутствии записи выводится сообщение: "Запись отсутствует".

КлючЗначение
--identityОбязательный ключ. Идентификатор компьютера: CNDN или UID.
--formatФормат вывода. По умолчанию используется формат JSON. Другие форматы могут быть добавлены при необходимости.

Атрибуты для изменения

--cn

Общее имя объекта

--description

Описание
--samaccountnameИмя входа Windows
--ownerВладелец объекта
--seealsoСсылка на связанные объекты

Организационная информация

--oОрганизация
--organizationnameОрганизация (полностью)
--organizationalunitnameОрганизационное подразделение (полностью)
--businesscategoryКатегория бизнеса
Пример использования
./dsapi modify-host --identity "cn=t-ds-twads01,ou=domaincontrollers,dc=example,dc=com" --description "Описание компьютера"

Внимание! При использовании команды должен быть указан один или более атрибутов для изменения.

./dsapi delete-host

Удаление компьютера.

Метод: DELETE /api/v1/hosts/{uid}

Результат:
Выводится сообщение об успешном удалении.
При отсутствии записи выводится сообщение: "Запись отсутствует".

КлючЗначение
--identityОбязательный ключ. Идентификатор компьютера: CNDN или UID.
Пример использования
./dsapi delete-host --identity "cn=t-ds-twads01,ou=domaincontrollers,dc=example,dc=com"

Управление подразделениями

./dsapi add-ou

Создание нового подразделения.

Метод: POST /api/v1/hierarchy/add

Результат:
Подразделение создано, выводится сообщение об успехе, запрашиваются и выводятся актуальные данные.

КлючЗначение

--ou

Обязательный ключ. Имя подразделения

Разрешены все символы за исключением символа двойных кавычек "

--parent
Обязательный ключ. DN родительского объекта

Из ключей "--parent" и "--ou" собирается полный DN нового объекта.
Объект создаётся внутри родительского объекта с DN, указанным в ключе "--parent".

Пример использования
./dsapi add-ou --ou "new_ou" --parent "ou=users,dc=example,dc=com"

./dsapi get-ou

Получение информации о подразделении.

Метод: GET /api/v1/entry/{uid}

Результат:
Выводятся актуальные данные подразделения или список дочерних элементов.
При отсутствии записи выводится сообщение: "Запись отсутствует".
При отсутствии дочерних элементов у записи выводится сообщение: Дочерние элементы отсутствуют.

КлючЗначение
--identity
Обязательный ключ. Идентификатор подразделения: DN или UID.

В зависимости от формата идентификатора поиск подразделения происходит по-разному:

  • Если передан UID, выполняется запрос /api/v1/entry/{uid} и проверка наличия атрибута ou, чтобы убедиться, что запрошено подразделение.
    Это сделано для защиты от ошибок при копировании, когда в буфере обмена случайно остался UID от предыдущих команд.
    Так как по эндпоинту /api/v1/entry/{uid} могут быть запрошены любые записи (пользователи, группы и т.д.).
  • Если передан DN, запрашиваются потомки родительского подразделения через /api/v1/hierarchy, а затем среди них ищется подразделение с DN.
    Пример: Запрошено подразделение с DN ou=hosts,dc=example,dc=com. Запрашиваются дочерние элементы dc=example,dc=com. Среди них происходит поиск подразделения с DN.
--childrenВывод дочерних элементов.
--formatФормат вывода. По умолчанию используется формат JSON. Другие форматы могут быть добавлены при необходимости.
Пример использования
./dsapi get-ou --identity "ou=users,dc=example,dc=com" --children

./dsapi modify-ou

Изменение атрибутов подразделения.

Метод: PUT /api/v1/attributes/{uid}

Результат:
Подразделение изменено, выводится сообщение об успехе, запрашиваются и выводятся актуальные данные.
При отсутствии записи выводится сообщение: "Запись отсутствует".

КлючЗначение
--identityОбязательный ключ. Идентификатор подразделения: DN или UID.
--formatФормат вывода. По умолчанию используется формат JSON. Другие форматы могут быть добавлены при необходимости.

Атрибуты для изменения

--ou

Имя подразделения
--organizationalunitnameИмя подразделения (полностью)

--description

Описание
--businesscategoryКатегория бизнеса

--seealso

Ссылка на связанные объекты

--searchguide

Руководство по поиску

--grouppolicylink

Ссылка на групповую политику

Организационная информация

--l

Населенный пункт

--localityname

Населенный пункт (полностью)

--st

Регион

--stateorprovincename

Название штата или провинции

--physicaldeliveryofficename

Офис доставки

--destinationindicator

Индикатор назначения

Почтовые и адресные данные

--postaladdress

Почтовый адрес

--postalcode

Почтовый индекс

--postofficebox

Почтовый ящик

--street

Улица

--streetaddress

Адрес улицы

--registeredaddress

Зарегистрированный адрес

--preferreddeliverymethod

Предпочтительный способ доставки

Контактные данные

--telephonenumber

Номер телефона

--facsimiletelephonenumber

Номер факса

--fax

Факс (сокращённо)

--internationalisdnnumber

Международный ISDN-номер

--x121address

X.121 адрес

--telexnumber

Номер телетекс

--teletexterminalidentity

Идентификатор телетекс-терминала
Пример использования
./dsapi modify-ou --identity "ou=users,dc=example,dc=com" --description "Описание подразделения"

Внимание! При использовании команды должен быть указан один или более атрибутов для изменения.

./dsapi delete-ou

Удаление подразделения.

Метод: DELETE /api/v1/hierarchy/{dn}

Результат:
Выводится сообщение об успешном удалении.
При отсутствии записи выводится сообщение: "Запись отсутствует".

 

КлючЗначение
--identityОбязательный ключ. Идентификатор подразделения: DN
Пример использования
./dsapi delete-ou --identity "ou=users,dc=example,dc=com"

./dsapi move-object

Перемещение объекта в иерархии.

Метод: POST /api/v1/hierarchy/move

Результат:
Объект перемещен, выводится сообщение со старым DN объекта, новым родителем и адресом сервера.

КлючЗначение

--object

Обязательный ключ. DN объекта для перемещения
--newparentОбязательный ключ. DN нового родительского объекта
Пример использования
./dsapi move-object --object "cn=lipov,ou=users,dc=example,dc=com" --newparent "ou=new_ou,ou=users,dc=example,dc=com"

Обсуждение