Help:ServerAdministration

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

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

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

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

1. Чтобы добавить учётную запись пользователя:

1) Нажмите кнопку Add user

2) Заполните поля появившейся формы

3) Установите переключатель, если нужно сменить пароль при первой авторизации

Окно создания учётной записи пользователя

2. Чтобы для существующей учетной записи пользователя поменять пароль:

1) Нажмите кнопку в столбце Action

2) В появившейся форме введите пароль в оба поля и установите переключатель, если нужно, чтобы пользователь сменил пароль после авторизации

Окно смены пароля пользователя

3. Чтобы архивировать пользователя:

1) Нажмите кнопку в столбце Action

2) При архивации пользователя с него будут сняты все роли и удалены его блокировки

3) Для восстановления пользователя нажмите кнопку в столбце Action

4) При восстановлении пользователя роли ему присвоены не будут

4. Чтобы добавить роль:

1) Нажмите кнопку Add role

2) Заполните поля появившейся формы

3) Укажите проект, к которому относится роль (ALL, если ко всем проектам) и права, которые будут доступны пользователю

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

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

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

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

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

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

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

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

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

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

1. Добавление и удаление проекта (при импорте проект создается автоматически).

2. Клонирование ветки (если при импорте указать флаг --branch <branch name> ветка создается автоматически).

3. Экспорт снимков с сервера в файл для дальнейшей загрузки его на другой сервер или в другой проект на этом же сервере. Детали описываются в разделе Перенос снимков.

4. Импорт снимка из файла. Для этого нажмите кнопку Import snapshot и в появившемся диалоге укажите файл для загрузки и имя нового снимка.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Разметка в контейнере состоит из множества размеченных маркеров. В целевой ветке уже может находится разметка. Все множество маркеров в исходной ветке можно разбить на два множества: «Уникальные» и «Общие». «Уникальные» — маркеры, которые есть только в исходной ветке. «Общие» — маркеры, которые есть как в ветке источнике, так и в ветке-приемнике. При выполнении операции копирования разметка на уникальных маркерах копируется всегда в ветку-приемник. Для «Общих» маркеров возможны несколько вариантов продолжения копирования. По умолчанию выбран пункт «Не копировать». В данном случае разметка на «Общих» маркерах в ветке-приемнике не изменяется. В случае выбора пункта «Перезаписать», разметка на «Общих» маркерах в целевом контейнере будет заменена на разметку из ветки-источника. При выборе пункта «Заменить, если новее» разметка из ветки-источника копируется в том случае, если ее метка времени более поздняя, чем та, которая указана в ветке-приемнике на данном маркере. Приведем пример. Пусть имеется контейнер 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 можно посмотреть все шаблоны, а также создать новый или клонировать существующий.

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

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

Для создания или изменения шаблонов следует обратиться к разработчикам 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.

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

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

При нажатии на кнопку 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": "ldap://192.168.11.71:389",
           "connectAs": "cn=ldap_service,cn=users,dc=domain,dc=home,dc=org",
           "password": "12345678",
           "ignoreCertCheck": true
         },
         "group": {
           "basedn": "cn=users",
           "filter": "(&(objectCategory=Group)(cn=dep_devops))",
           "userMember": "member",
           "display":"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",
           "ignoreCertCheck": true,
         "caCertFiles":["/etc/ssl/certs/a*","/etc/ssl/certs/my_certs/*"]
         },
         "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
• connectAs — имя пользователя в формате DN, из под которого будут производится операции в LDAP каталоге
• password — пароль пользователя
• ignoreCheck — не проверять сертификат в случае ldaps:// соединения. Полезно при самоподписанных сертификатах. Если флаг установлен в значение false, необходимо установить значение поля caCertFiles.
• CaCertFiles — массив значений, описывающих какие файлы корневых сертификатов добавлять в конфигурацию svacer. Формат файлов сертификатов — PEM

• group — подсекция, описывает параметры проверки принадлежности пользователя к группе

• basedn — RDN, добавляемая к общей DN. Относительно этого DN производится поиск группы
• filter — фильтр, используемый при поиске группы. Необходимо, если надо указать несколько групп
• userMember — атрибут в группе, содержащий пользователей, принадлежащих группе
• display — атрибут, содержащий имя группы для отображения

• user — подсекция, описывает параметры получения информации о пользователе

• basedn — RDN, добавляемая к общей DN. Относительно этого DN производится поиск группы
• filter — фильтр, используемый при поиске пользователей.
• login — атрибут, в котором находится login пользователя
• group — атрибут в пользователе, на который ссылается атрибут group.userMember (обычно это «dn» пользователя)
• info — подсекция описывающая в каких атрибутах находится информация о пользователе

• display — атрибут, содержащий полное имя пользователя для отображения (ФИО)
• email — атрибут с почтовым адресом
• firstName — атрибут с именем
• lastName — атрибут с фамилией

• enabled — использовать или нет данный сервер

Использование 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 сервера.

Также данные пользователей можно обновить с помощью интерфейса командной строки. Для этого можно использовать подкоманду 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>