Help:ServerAdministration

From SvacerWiki
Jump to navigation Jump to search

Администрирование сервера

Функции, описанные в этом разделе, доступны только пользователю с ролью admin.

Учетные записи и роли пользователей

В окне Settings > Users отображаются все существующие пользователи. В этом окне:

1. Чтобы добавить учётную запись пользователя:
1) Нажмите кнопку Add user
2) Заполните поля появившейся формы
3) Установите переключатель, если нужно сменить пароль при первой авторизации

AddUser
Окно создания учётной записи пользователя
2. Чтобы для существующей учетной записи пользователя поменять пароль:
1) Нажмите кнопку KeyButton в столбце Action
2) В появившейся форме введите пароль в оба поля и установите переключатель, если нужно, чтобы пользователь сменил пароль после авторизации

ChangePassword
Окно смены пароля пользователя
3. Чтобы архивировать пользователя:
1) Нажмите кнопку ArchiveButton в столбце Action
2) При архивации пользователя с него будут сняты все роли и удалены его блокировки
3) Для восстановления пользователя нажмите кнопку UnzipButton в столбце Action
4) При восстановлении пользователя роли ему присвоены не будут
4. Чтобы добавить роль:
1) Нажмите кнопку Add role
2) Заполните поля появившейся формы
3) Укажите проект, к которому относится роль (ALL, если ко всем проектам) и права, которые будут доступны пользователю

CreateNewRole
Настройка роли и прав доступа

Семантика ролей пользователя

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

Действие Область Эффект
READ Проект Получение списка веток, получение списка предупреждений из любой ветки проекта, экспорт данных из веток проекта
READ Ветка Получение списка предупреждений из ветки проекта, экспорт данных из ветки
WRITE Ветка/Проект Импортирование данных на конкретную ветку или на любую ветку проекта
REVIEW Ветка/Проект Возможность менять разметку и добавлять/менять комментарии на предупреждениях

Существует специальная область ALL, которая означает все проекты и ветки. Существуют следующие специальные роли с особым значением, какие не могут быть удалены из системы:

Роль Эффект
importer Возможность загрузки данных анализа посредством команды svacer upload
review_master Разметка, произведенная пользователем с данной ролью не может быть переопределена пользователем без данной роли
admin Дает полномочия администратора сервера
all_projects Доступ на все операции и ко всем проектам, но без административных привилегий

Ведение списка проектов

В окне Settings > Projects отображаются все проекты с ветками и снимками.

ProjectsList

Список проектов

В этом окне доступны:

1. Добавление и удаление проекта (при импорте проект создается автоматически).
2. Клонирование ветки (если при импорте указать флаг --branch <branch name> ветка создается автоматически).
3. Экспорт снимков с сервера в файл для дальнейшей загрузки его на другой сервер или в другой проект на этом же сервере. Детали описываются в разделе Перенос снимков.
4. Импорт снимка из файла. Для этого нажмите кнопку Import snapshot и в появившемся диалоге укажите файл для загрузки и имя нового снимка.

SnapshotImport
Импорт снимка

Настройка фильтров веток и проектов

В окне Settings > Filters можно создать общие фильтры на ветку или весь проект. Для смены scope с проекта на ветку или обратно следует нажать на кнопку project/branch в столбце Scope.

ProjectBranchesFilters

Окно фильтров веток и проектов

После применения фильтров в окне Review отображаются только маркеры, удовлетворяющие условиям.

Просмотр информации о сервере

В окне Settings > Server information отображаются:

  • параметры, с которыми запущен сервер;
  • логи сервера;
  • журнал базы данных;

ServerInfo

Информация о сервере

Копирование разметки

Для копирования разметки между контейнерами необходимо перейти в окно Settings > Projects и далее выделить ветку, из которой необходимо скопировать разметку. К примеру, zstd_130 на рисунке ниже.

MarkupCopingBranch

Выбор ветки для копирования разметки

Далее необходимо нажать на кнопку «…» и в появившемся меню выбрать Copy markup. В результате появляется окно выбора контейнера, в который будет выполнено копирование.

MarkupCoping

Копирование разметки

Разметка в контейнере состоит из множества размеченных маркеров. В целевой ветке уже может находится разметка. Все множество маркеров в исходной ветке можно разбить на два множества: «Уникальные» и «Общие». «Уникальные» — маркеры, которые есть только в исходной ветке. «Общие» — маркеры, которые есть как в ветке источнике, так и в ветке-приемнике. При выполнении операции копирования разметка на уникальных маркерах копируется всегда в ветку-приемник. Для «Общих» маркеров возможны несколько вариантов продолжения копирования. По умолчанию выбран пункт «Не копировать». В данном случае разметка на «Общих» маркерах в ветке-приемнике не изменяется. В случае выбора пункта «Перезаписать», разметка на «Общих» маркерах в целевом контейнере будет заменена на разметку из ветки-источника. При выборе пункта «Заменить, если новее» разметка из ветки-источника копируется в том случае, если ее метка времени более поздняя, чем та, которая указана в ветке-приемнике на данном маркере. Приведем пример. Пусть имеется контейнер A с разметкой {(M1,D1),(M2,D2), (M3,D3)} и контейнер B с разметкой {(M4,D4), (M2,D5), (M3,D6)}, где M — это маркер, а D — разметка (включая метку времени). Операцию сравнения на разметке обозначим как >. Если метка времени в D1 больше, чем в D2, D1>D2. Пусть D2>D5, а D3<D6. Тогда операция копирования всегда скопирует разметку D1 (но не сам маркер), так как маркер M1 новый для контейнера B. Маркеры M2, M3 — общие для двух контейнеров, поэтому какая разметка будет в контейнере-приемнике будет зависеть от выбранного варианта разрешения конфликта. Если будет выбран пункт «Не копировать», то в контейнере B на маркерах M2,M3 будет разметка D5,D6 соответственно. Если выбран пункт «перезаписать», то на M2,M3 будет разметка D2,D3. Если выбран пункт «Заменить, если новее», то на M2,M3 разметка будет: D2,D6, так как D2>D5 и D6>D3 При выполнении копирования наличие маркера в ветке приемнике не проверяется. При успешном копировании выводится всплывающее сообщение вида:

   Operation done. Total count: X, Overwritten: Y. 

Данное сообщение означает, что всего было скопировано X инвариантов вместе с разметкой и среди скопированных инвариантов Y штук было скопировано с заменой.

Создание и изменение шаблонов разметки

В окне Settings > Markup templates можно посмотреть все шаблоны, а также создать новый или клонировать существующий.

MarkupTemplates

Шаблоны разметки нужны для импорта/экспорта разметки. С их помощью комментарии в исходном коде будут преобразовываться в разметку на сервере истории и обратно. Шаблон с именем DEFAULT есть всегда, его нельзя отредактировать или удалить. На рисунке ниже представлены все поля шаблона, доступные для редактирования.

MarkupTemplateEditing

Редактирование шаблона разметки

Для создания или изменения шаблонов следует обратиться к разработчикам Svace History Server.

Поддержка протокола LDAP для аутентификации пользователей

Общий принцип аутентификации

Схема аутентификации с помощью протокола LDAP следующая:

  1. Сервер запускается с указанием конфигурационного файла с настройками для LDAP аутентификации
  2. В форме аутентификации пользователь выбирает нужный тип аутентификации (svacer или LDAP)
  3. При выборе аутентификации LDAP, после заполнения необходимых параметров, запрос на аутентификацию отправляется на сервер svacer
  4. Сервер Svacer, используя настройки из конфигурационного файла, обращается к внешнему LDAP серверу и проводит проверку пользователя
  5. В случае успешной аутентификации, в БД сервера Svacer создается запись (если ее еще нет) для пользователя, чтобы можно было управлять ролями данного пользователя
  6. Сервер возвращает токен безопасности для дальнейшей работы, аналогичный токену, возвращаемому при аутентификации локальных пользователей

Для каждого пользователя, успешно прошедшего проверку на LDAP сервере, создается локальная запись в БД Svacer. Управлять таким пользователем можно как и обычным пользователем, за исключением:

  • Пользователю нельзя сменить пароль
  • Пользователь не может сменить пароль самостоятельно
  • В случае отсутствия связи между сервером Svacer и сервером LDAP, данный пользователь не сможет зайти в систему

Запуск сервера с поддержкой LDAP

Сервер может быть запущен как в с поддержкой аутентификации через LDAP, так и без. Для того, чтобы включить аутентификацию через LDAP необходимо указать конфигурационный файл. Типовой пример конфигурационного файла для подключения к контроллеру домена MS ActiveDirectory или серверу openLDAP можно получить с помощью команды:

   svacer ldap print

Запуск сервера с поддержкой LDAP осуществляется командой:

   svacer  server  --ldap ldap.json

При запуске сервер svacer формирует список доступных для LDAP аутентификации серверов и выводит соответствующее сообщение. Ниже приведен лог сервера, запущенного с поддержкой протокола LDAP.

LdapServerAdded

После запуска сервера svacer с поддержкой LDAP в GUI становится активна вкладка LDAP.

Для аутентификации с помощью LDAP необходимо выбрать сервер из выпадающего списка.

LdapServerChoose

При нажатии на кнопку Details появляется более подробная информация о сервере и его доступности (параметр Alive). Доступность сервера LDAP проверяется в момент запуска сервера Svacer, при аутентификации пользователя, а также (в случае наличия соответствующего параметра в конфигурационном файле) периодически. В случае конфигурации сервера Svacer с поддержкой LDAP можно отключить возможность аутентификации пользователей встроенными средствами сервера Svacer (вкладка Svacer на странице входа). В этом случае вкладка Svacer на странице входа будет неактивной и пользователи смогут заходить в систему только с помощью LDAP аутентификации. Данное поведение распространяется и на работу с сервером с помощью интерфейса командной строки.

Для отключения возможности аутентификации встроенными средствами сервера Svacer нужно использовать опцию disable-svacer-auth.

Пример:

   svacer server --ldap ldap.json --disable-svacer-auth

Конфигурационный файл сервера для поддержки LDAP

Типовой пример конфигурации представлен ниже.

   {
     "servers": [
       {
         "name": "active_directory",
         "basedn": "dc=domain,dc=home,dc=org",
         "useGroup": true,
         "hideURL": true,
         "checkAlivePeriod": 60,	
         "connection": {
           "url": "ldaps://192.168.11.71:636",
           "mirrors":["ldaps://192.168.11.72:636","ldaps://192.168.11.73:636"]
           "connectAs": "cn=ldap_service,cn=users,dc=domain,dc=home,dc=org",
           "password": "12345678",
           "ignoreCertCheck": false,
           "caCertFiles":["/etc/ssl/certs/a*","/etc/ssl/certs/my_certs/*"]
         },
         "group": {
           "basedn": "cn=users",
           "filter": "(&(objectCategory=Group)(cn=dep_devops))",
           "userMember": "member",
           "display":"cn",
           "svacerRole":"cn"
         },
         "user": {
           "basedn": "cn=users",
           "filter": "(&(objectCategory=Person)(sAMAccountName=*))",
           "login": "sAMAccountName",
           "group": "dn",
           "info": {
             "display": "cn",
             "email": "email",
             "firstName": "givenName",
             "lastName": "sn"
           }
         },
         "enabled": true
       },
       {
         "name": "open_ldap",
         "basedn": "dc=example,dc=com",
         "useGroup": true,
         "connection": {
           "url": "ldap://127.0.0.1:389",
           "connectAs": "cn=admin,dc=example,dc=com",
           "password": "12345678"
         },
         "group": {
           "basedn": "ou=groups",
           "filter": "(&(objectClass=groupOfNames)(cn=svacer))",
           "userMember": "member",
           "display":"cn"
         },
         "user": {
           "basedn": "ou=users",
           "filter": "(&(objectClass=PosixAccount))",
           "login": "uid",
           "group": "dn",
           "info": {
             "display": "dn",
             "email": "mail",
             "firstName": "givenName",
             "lastName": "sn"
           }
         },
         "enabled": true
       }
     ]
   }

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

  • name — произвольное имя (уникальное для каждого сервера)
  • basedn — DN относительно которого будут проводится все операции в LDAP каталоге
  • useGroup — проверять ли принадлежность пользователя к группе
  • hideURL — не передавать сетевой адрес LDAP сервера. Конечные пользователи будут видеть в выпадающем списке только имя сервера, указанное в поле name. В поле URL будет пустая строка.
  • checkAlivePeriod — Промежуток времени в секундах, который должен проходить между периодическими проверками доступности сервера LDAP. Если параметр равен 0 или не указан, такая проверка не проводится.
  • connection — подсекция, описывающая параметры соединения с сервером
  • url — адрес сервера, формата: ldap[s]://domain:port В случае использования TLS для подключения к LDAP серверу, необходимо указать правильный порт (по умолчанию 636).
  • mirrors — список хостов, которые будут использованы в случае недоступности основного хоста, указанного в поле URL. Формат указания хостов тот же, что и в поле URL. Префикс ldap[s] должен быть одинаковым для всех хостов и совпадать с префиксом в поле URL.
  • connectAs — имя пользователя в формате DN, из под которого будут производится операции в LDAP каталоге
  • password — пароль пользователя
  • ignoreCheck — не проверять сертификат в случае ldaps:// соединения. Полезно при самоподписанных сертификатах. Если флаг установлен в значение false, необходимо установить значение поля caCertFiles.
  • CaCertFiles — массив значений, описывающих какие файлы корневых сертификатов добавлять в конфигурацию Svacer. Формат файлов сертификатов — PEM
  • group — подсекция, описывает параметры проверки принадлежности пользователя к группе
  • basedn — RDN, добавляемая к общей DN. Относительно этого DN производится поиск группы
  • filter — фильтр, используемый при поиске группы. Необходимо, если надо указать несколько групп
  • userMember — атрибут в группе, содержащий пользователей, принадлежащих группе
  • display — атрибут, содержащий имя группы для отображения
  • svacerRole — атрибут, из которого будет извлечено имя роли, созданной в Svacer, и автоматически сопоставляемой с пользователем.
  • user — подсекция, описывает параметры получения информации о пользователе
  • basedn — RDN, добавляемая к общей DN. Относительно этого DN производится поиск группы
  • filter — фильтр, используемый при поиске пользователей.
  • login — атрибут, в котором находится login пользователя.
  • group — атрибут в пользователе, на который ссылается атрибут group.userMember (обычно это «dn» пользователя)
  • info — подсекция описывающая в каких атрибутах находится информация о пользователе
  • display — атрибут, содержащий полное имя пользователя для отображения (ФИО)
  • email — атрибут с почтовым адресом
  • firstName — атрибут с именем
  • lastName — атрибут с фамилией
  • enabled — использовать или нет данный сервер

Примеры конфигурации взаимодействия с LDAP сервером

Рассмотрим пример обработки запроса на вход в систему LDAP пользователя, указавшего значение ivanov_ii в поле логина и выбравшего конфигурацию active_directory из примера выше

  1. Svacer создает служебное подключение к хосту 192.168.11.71 со следующими параметрами
    • используется TLS соединение (ldaps префикс)
    • порт 636
    • проверяется сертификат LDAP сервера (ignoreCertCheck = false); для проверки используются сертификаты CA (из папки /etc/ssl/certs — все сертификаты, начинающиеся с буквы a; из папки /etc/ssl/certs/my_certs/ — все сертификаты)
    • логин для подключения к LDAP серверу: "cn=ldap_service,cn=users,dc=domain,dc=home,dc=org" (connectAs); пароль: 12345678 (password)
  2. Если подключение к хосту невозможно (хост недоступен), то пробуются хосты 192.168.11.72,192.168.11.73 с параметрами, аналогичными параметрам пункта 1
  3. Если подключение невозможно, процесс входа завершается с ошибкой
  4. Производится поиск пользователя в LDAP каталоге со следующими параметрами:
    • строка запроса: (&(sAMAccountName=ivanov_ii)((&(objectCategory=Person)(sAMAccountName=*)))), sAMAccountName — взят из поля user.login конфиг файла; ivanov_ii — введено пользователем; (&(objectCategory=Person)(sAMAccountName=*)) — взято из поля user.filter конфиг файла
    • начальный узел, с которого будет произведен поиск: cn=users, dc=domain,dc=home,dc=org
    • поиск производится по всему поддереву
  5. Если пользователей не найдено или найдено больше 1 пользователя, процесс входа завершается с ошибкой
  6. Флаг useGroup = true, поэтому производится дополнительная проверка группы пользователя
    • выполняется поиск групп в каталоге LDAP со следующими параметрами:
      • строка запроса: (&(objectCategory=Group)(cn=dep_devops)) — взято из поля group.filter
      • начальный узел: cn=users, dc=domain,dc=home,dc=org, где cn=users — взято из поля group.basedn; значение dc=domain,dc=home,dc=org — взято из поля basedn конфиг файла
      • поиск производится по всему поддереву
      • определяется список пользователей группы (каждому пользователю соответствует значение атрибута с именем member (взято из поля group.userMember конфиг файла))
    • Если ни одной группы не найдено, то процесс входа завершается с ошибкой
    • Определяются группы, в которые входит пользователь. Для этого для каждой группы, найденной в пункте выше, просматривается список пользователей и ищется значение cn=ivanov_ii,cn=users,dc=domain,dc=home,dc=org (в поле user.group конфиг файла указано значение dn, что означает, что необходимо использовать DN пользователя для данной процедуры). Если атрибут найден, считается что пользователь принадлежит группе.
    • Если пользователь не принадлежит ни к одной группе, процесс входа завершается с ошибкой
  7. Производится попытка подключения к хосту LDAP с параметрами, аналогичными параметрам из пункта 1, за исключением логина (cn=ivanov_ii,cn=users,dc=domain,dc=home,dc=org) и пароля пользователя (введен в поле пароль формы входа)
  8. Если подключение не удалось создать, то процесс входа завершается с ошибкой
  9. Процесс аутентификации пользователя произведен успешно
  10. Производится создание локального пользователя svacer с именем ivanov_ii, если его еще нет
  11. Так как useGroup = true и указан атрибут svacerRole с непустым значением, то производится привязка ролей Savcer пользователя на основе его участия в группах LDAP (смотри соответствующий пункт)

Привязка группы LDAP к роли Svacer

Возможно автоматическое назначение пользователям LDAP ролей Svacer. Для использования данной функции необходимо выполнить следующие предварительные действия:

  • Администратор LDAP сервера создает в каталоге LDAP нужные группы (например cn=users,ou=svacer,dc=example,dc=com и cn=admins, ou=svacer,dc=example,dc=com), которые будут привязаны к ролям Svacer.
  • Администратор LDAP сервера помещает пользователей LDAP в соответствующие LDAP группы (cn=users,ou=svacer,dc=example,dc=com или cn=admins, ou=svacer,dc=example,dc=com)
  • Администратор Svacer создает роли в Svacer, имеющие в точности такое же название, как значение атрибута, указанного в поле svacerRole конфигурационного файла. В пример можно использовать аттрибут cn и в этом случае необходимо создать роли users и admins
  • Администратор Svacer добавляет в конфигурационный файл в поле svacerRole имя атрибута, по которому будет производится привязка. Для примера выше — строчку svacerRole="cn"

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

  • Производится поиск групп, к которым принадлежит пользователь. Поиск производится по параметрам, указанным в секции group конфигурационного файла. Для примера, пользователь может состоять в следующих группах: (cn=users,ou=svacer,dc=example,dc=com), (cn=dep_dev,dc=example,dc=com)
  • Для каждой найденной группы, выбирается значение атрибута, указанного в поле svacerRole. В примере — имя атрибута cn. Получаются два имени: users, dep_dev
  • Производится поиск ролей Svacer с именем users и dep_dev. Если такие роли найдены, то пользователю они будут добавлены. Так как в примере роль dep_dev не создана, то будет добавлена только роль users.

Удаление ролей автоматически не производится. Вместо этого предлагается ручного режим синхронизации ролей пользователя. Для синхронизации ролей с текущими группами, в которых состоит пользователь, используется команда cli

 svacer ldap sync_roles --login [user_login] --server [server_name] --apply

Данная команда проверит наличие пользователя user_login в соответствующей роли группе LDAP и если его в группе не будет, уберет роль у пользователя. Также команда добавит недостающие роли, на основе механизма, описанного выше (при входе пользователя). Флаг apply позволяет "оценить" получаемые изменения прежде чем они будут применены. По умолчанию флаг apply = false.

Использование CLI сервера Svacer с поддержкой LDAP

Для выполнения некоторых действий в cli с помощью команды svacer требуется аутентификация пользователя. Для аутентификации с помощью ldap сервера необходимо указать в команде кроме имени пользователя и пароля имя сервера с помощью флага ldap_server (имя сервера регистр-зависимо). Например:

   ./svacer quickdiff --user loginok --password loginok --ldap_server openLDAP2 --project zstd --branch zstd_14 --snapshot_v1 v1.4.1 --snapshot_v2 zstd_140

Если флаг ldap_server не указан, аутентификация производится механизмами сервера svacer, как и в предыдущих версиях. Параметр ldap_server можно опустить, указав сервер в переменной окружения SVACER_LDAP_SERVER. Например:

   SVACER_LDAP_SERVER=“openLDAP2“ ./svacer quickdiff --user loginok --password loginok --project zstd --branch zstd_14 --snapshot_v1 v1.4.1 --snapshot_v2 zstd_140

Для получения списка поддерживаемых свейсером LDAP серверов можно использовать команду:

   ./svacer ldap servers --host 127.0.0.1 --port 8080

Вывод содержит два столбца (имя и URL сервера). В качестве значения для параметра ldap_server необходимо использовать содержимое первого столбца.

Обновление данных LDAP пользователей

Для каждого LDAP пользователя создается соответствующая ему запись в БД Svacer, в которую включается ФИО из LDAP и адрес его электронной почты. Через какое-то время данные пользователей могут меняться, в этом случае возможно обновить данные LDAP пользователей, хранящиеся в Svacer, синхронизировав их с данными LDAP сервера. Для обновления данных одного пользователя можно воспользоваться окном редактирования пользователя, в котором можно нажать кнопку Load from LDAP. В соответствующие окна будут добавлены данные, загруженные из LDAP сервера.

ChangeUserProfile

Также данные пользователей можно обновить с помощью интерфейса командной строки. Для этого можно использовать подкоманду updateUsers команды ldap. Общий синтаксис команды выглядит следующим образом:

   ./svacer ldap updateUsers --onlyEmpty

Флаг onlyEmpty позволяет обновлять только пустые поля ФИО и eMail. Заполненные поля не будут изменены. Команда обновит данные всех пользователей, записи о которых имеются в базе Svacer.

Поддержка сквозной аутентификации

Svacer поддерживает сквозную аутентификацию через reverse proxy. Для этого используется опция proxy-mode. При включении этой опции есть возможность проходить аутентификацию (используя HTTP Basic Authentication) на reverse proxy сервере и использовать эти данные для аутентификации на сервере Svacer.

При включенном proxy-mode используется header с прокси Authorization Basic ..., откуда Svacer берет имя пользователя и пароль, проверяет и аутентифицирует пользователя, если аккаунт с таким логином и паролем существует в БД пользователей Svacer.

Пример запуска сервера с поддержкой сквозной аутентификации:

   ./svacer server --proxy-mode

Поддержка OAuth

Svacer поддерживает авторизацию по протоколу OAuth. Для авторизации используются запросы GET /api/oauth/authorize и POST /api/oauth/token в соответствии со стандартом.

API-вызовы для управления клиентами

  • GET /api/oauth/clients — получение всех клиентов для текущего пользователя или всех клиентов текущего сервера для админа;
  • GET /api/oauth/client?client_id={client_id} — получение клиента по id;
  • POST /api/oauth/client — создание нового клиента;
  • PUT /api/oauth/client — изменение данных клиента;
  • DELETE /api/oauth/client/{client_id} — удаление клиента.

Клиенты могут быть зарегистрированы на панели Settings > OAuth Clients. Клиент содержит в себе следующие поля:

  • ID — генерируется на сервере и не изменяется впоследствии;
  • Name — задается пользователем при создании и может впоследствии меняться; отображается на странице подтверждения авторизации;
  • Secret — генерируется на сервере, не изменяется впоследствии и возвращается только в ответе на запрос создания;
  • Domain — задается пользователем и может впоследствии меняться; используется как redirect_uri, если в запросе authorize отсутствует это поле;
  • UserId — извлекается из сессии во время создания и не изменяется впоследствии.

Hooks

Для получения данных Hooks при запуске сервера нужно указать опцию --hooks <path to JSON file>. Эта опция задаёт файл, содержащий информацию о расширении сервера посредством хуков, которые пользователь может вызывать из web-интерфейса. Каждый хук соответствует некоторому процессу или скрипту, который сервер запускает в ответ на вызов соответствующей команды из web-интерфейса. Формат файла Hooks следующий:

   {
     "hooks": [
       {
         "id": "<id>",
         "label": "<label >",
         "target": "<target>",
         "input": ["<param1>", "<param2>",…],
         "cmd": "<path to executable>",
         "args": ["<arg1>", “<arg2>”, …]
       },
       ...
     ]
   }

Параметры Hooks

Параметр Описание
id Идентификатор хука.
Должен быть уникальным в файле
label Имя команды, которую пользователь видит в web-интерфейсе
target Место в UI, в которое будет добавлена команда.

Сейчас поддерживается только одно значение — default. Оно соответствует вкладке Details на правой панели пользовательского интерфейса

input Параметры, которые можно передать в запускаемый процесс, исходя из контекста вызова команды в web-интерфейсе.

Поддерживаемые значения:

  • markerID — UUID идентификатор маркера;
  • branchID — UUID идентификатор ветки;
  • snapshotID — UUID идентификатор снимка;
  • projectID — UUID идентификатор проекта;
  • url — URL маркера в web-интерфейсе, на котором была вызвана команда;
  • marker — будет заменен на полное имя временного файла, содержащего сериализованное в JSON представление маркера, который включает в себя его трассу и информацию о разметке
cmd Полный путь к процессу, который будет запущен. Не должен включать аргументы запуска
args Аргументы, передаваемые в запускаемый процесс. Полный список аргументов запускаемого процесса состоит из списка <args> и списка значений, соответствующих полю <input>

Одним из типичных сценариев использования хуков является создание кейсов для выбранного предупреждения в системах отслеживания ошибок, таких как Jira и Gitlab. Примеры скриптов для этого можно найти на странице Примеры использования хуков.