Help:CLI: Difference between revisions

From Svacer Wiki
No edit summary
m (minor fixes)
Line 3: Line 3:
Запустив Svacer без параметров, можно получить информацию о доступных командах. Дополнительная информация о каждой команде доступна при использовании опции '''--help'''
Запустив Svacer без параметров, можно получить информацию о доступных командах. Дополнительная информация о каждой команде доступна при использовании опции '''--help'''


    svacer <command name> --help
  svacer <command name> --help


Общий формат командной строки
Общий формат командной строки


    svacer [global options] command [command options] [arguments...]
  svacer [global options] command [command options] [arguments...]


Глобальные опции относятся ко всем командам.
Глобальные опции относятся ко всем командам.
Line 35: Line 35:


Общий вид команды следующий:
Общий вид команды следующий:
    '''svacer pdfgen''' --cmpMode [none|new|missing|matched|same] --project [name|id] --branch [name|id] --snapshot [name|id] [--targetProject [name|id] --targetBranch [name|id] --targetSnapshot [name|id]] [--file [re_exp] --checker [re_exp] --severity [re_exp] --review [re_exp]] --outFile report_name --tz time_zone --lang report_lang
  svacer pdfgen --cmpMode [none|new|missing|matched|same] --project [name|id] --branch [name|id] --snapshot [name|id] [--targetProject [name|id] --targetBranch [name|id] --targetSnapshot [name|id]] [--file [re_exp] --checker [re_exp] --severity [re_exp] --review [re_exp]] --outFile report_name --tz time_zone --lang report_lang


Описание параметров:
Описание параметров:
Line 47: Line 47:


Для создания отчета без использования режима сравнения, необходимо указать cmpMode в значение none (это значение используется по умолчанию).
Для создания отчета без использования режима сравнения, необходимо указать cmpMode в значение none (это значение используется по умолчанию).
Для предварительного формирования таблицы маркеров с учетом сравнения, использовать значения cmpMode [new, missing, same, matched]. Названия этих режимов аналогичны названиями в GUI. При этом требуется указание как минимум одного параметра из списка: targetProject, targetBranch, targetSnapshot. Если какие-то параметры target* не указаны, они будут установлены в значение исходных (project → targetProject, branch → targetBranch, ). Сформированные на предварительном этапе  маркеры, проходят механизм фильтраций (параметры: severity, file, review, checker), после чего происходит создание отчета.
Для предварительного формирования таблицы маркеров с учетом сравнения, использовать значения cmpMode [new, missing, same, matched]. Названия этих режимов аналогичны названиями в GUI. При этом требуется указание как минимум одного параметра из списка: targetProject, targetBranch, targetSnapshot. Если какие-то параметры target* не указаны, они будут установлены в значение исходных (project → targetProject, branch → targetBranch, ...). Сформированные на предварительном этапе  маркеры, проходят механизм фильтраций (параметры: severity, file, review, checker), после чего происходит создание отчета.


Для создания отчета можно также использовать public API. Необходимо использовать следующие параметры:
Для создания отчета можно также использовать public API. Необходимо использовать следующие параметры:
Line 82: Line 82:


Синтаксис:
Синтаксис:
    svacer markup --user <user> --password <password> --project <project id or name> --branch <branch id or name> --snapshot <snapshot id or name> import --template <name> [--excludePaths <path1, path2, ... ,pathN> --from-build-object]
  svacer markup --user <user> --password <password> --project <project id or name> --branch <branch id or name> --snapshot <snapshot id or name> import --template <name> [--excludePaths <path1, path2, ... ,pathN> --from-build-object]


Где:  
Где:  
Line 97: Line 97:
Для подавления найденных предупреждений следует использовать следующий формат разметки в исходном коде
Для подавления найденных предупреждений следует использовать следующий формат разметки в исходном коде


    //svacer_review: -<warn class>[|-<warn class>]+  
  //svacer_review: -<warn class>[|-<warn class>]+  


Пример:  
Пример:  


      if (!strncmp("--filelimit",argv[i],11)) {
  if (!strncmp("--filelimit",argv[i],11)) {
        j = 11; //svacer_review: -UNUSED_VALUE
    j = 11; //svacer_review: -UNUSED_VALUE
        if (*(argv[i]+11) == '=') {
    if (*(argv[i]+11) == '=') {


Комментарий должен быть расположен в конце строки, где ожидается предупреждение от анализатора Svace.
Комментарий должен быть расположен в конце строки, где ожидается предупреждение от анализатора Svace.
Line 110: Line 110:


==== Описание шаблона разметки DEFAULT ====
==== Описание шаблона разметки DEFAULT ====
Сервер позволяет добавить собственные шаблоны разметки, для удобства добавлен не удаляемый шаблон DEFAULT. Список шаблонов можно увидеть в '''Settings > Markup templates''' (при наличии у пользователя доступа).
Сервер позволяет добавить собственные шаблоны разметки, для удобства добавлен неудаляемый шаблон DEFAULT. Список шаблонов можно увидеть в '''Settings > Markup templates''' (при наличии у пользователя доступа).


Шаблон можно использовать как для импорта, так и для экспорта разметки, поэтому можно проверить ожидаемый формат [[Help:UI_manual#Экспорт_кода_с_разметкой|через выгрузку кода с указанием шаблона]].
Шаблон можно использовать как для импорта, так и для экспорта разметки, поэтому можно проверить ожидаемый формат [[Help:UI_manual#Экспорт_кода_с_разметкой|через выгрузку кода с указанием шаблона]].


В шаблоне DEFAULT каждая разметка описывается на отдельной строчке перед маркером, при необходимости можно использовать несколько строчек. Импорт разметки со статусом Undecided (или не правильным) не производится (включая комментарий).
В шаблоне DEFAULT каждая разметка описывается на отдельной строчке перед маркером, при необходимости можно использовать несколько строчек. Импорт разметки с неправильным статусом или со статусом Undecided не производится, включая комментарий.


Пример:
Пример:


    //svacer_review: FORMAT_STRING.PARAM_EXCESS r:Confirmed|s:Minor|a:Undecided|c:
  //svacer_review: FORMAT_STRING.PARAM_EXCESS r:Confirmed|s:Minor|a:Undecided|c:
    //svacer_review: UNINIT.LOCAL_VAR r:Confirmed|s:Unspecified|a:Fix required|c:will be fixed
  //svacer_review: UNINIT.LOCAL_VAR r:Confirmed|s:Unspecified|a:Fix required|c:will be fixed
    printf("v = %d", fl3(), i);
  printf("v = %d", fl3(), i);


Разметка нескольких одинаковых предупреждений на одной строчке проблематична, гарантируется только что разметка будет применена к маркеру с таким названием.
Разметка нескольких одинаковых предупреждений на одной строчке проблематична, гарантируется только что разметка будет применена к маркеру с таким названием.
Line 128: Line 128:


Синтаксис:
Синтаксис:
    svacer markup update --user <user> --password <password> --project <project id or name> --branch <branch id or name> --pathPrefix <prefix:replacement; prefix:replacement> [<snapshot id or name>1, <snapshot id or name>2, , <snapshot id or name>N]
  svacer markup update --user <user> --password <password> --project <project id or name> --branch <branch id or name> --pathPrefix <prefix:replacement; prefix:replacement> [<snapshot id or name>1, <snapshot id or name>2, ..., <snapshot id or name>N]


Где:  
Где:  
Line 142: Line 142:


Список подавленных предупреждений (печатает JSON)
Список подавленных предупреждений (печатает JSON)
    svacer markup [auth/selection] suppress list
  svacer markup [auth/selection] suppress list
Пример:
 
    svacer markup --user admin --password admin --project tree-command suppress list
Пример
  svacer markup --user admin --password admin --project tree-command suppress list
 


Подавить предупреждение
Подавить предупреждение
    svacer markup [auth/selection] suppress add id1 id2 id3
  svacer markup [auth/selection] suppress add id1 id2 id3
Пример:
 
    svacer markup --user admin --password admin --project tree-command suppress add 29d298cd-752d-4d19-b535-2089a72a96af
Пример
  svacer markup --user admin --password admin --project tree-command suppress add 29d298cd-752d-4d19-b535-2089a72a96af
 


Убрать подавление предупреждения
Убрать подавление предупреждения
    svacer markup [auth/selection] suppress remove id1 id2 id3  
  svacer markup [auth/selection] suppress remove id1 id2 id3
Пример:
 
    svacer markup --user admin --password admin --project tree-command suppress remove 29d298cd-752d-4d19-b535-2089a72a96af
Пример
  svacer markup --user admin --password admin --project tree-command suppress remove 29d298cd-752d-4d19-b535-2089a72a96af
 


Убрать все подавления
Убрать все подавления
    svacer markup [auth/selection] suppress remove
  svacer markup [auth/selection] suppress remove
Пример:
 
    svacer markup --user admin --password admin --project tree-command suppress remove
Пример
  svacer markup --user admin --password admin --project tree-command suppress remove


Список предупреждений с ID доступен посредством public REST API. Функциональность предназначена для интеграции со сторонними инструментами и встраивание в CI/CD pipeline.
Список предупреждений с ID доступен посредством public REST API. Функциональность предназначена для интеграции со сторонними инструментами и встраивания в CI/CD pipeline.
На текущий момент информация о подавленных предупреждения недоступна в веб-интерфейсе.
На текущий момент информация о подавленных предупреждениях недоступна в веб-интерфейсе.


При экспортировании снимка где есть подавленные предупреждения, сами предупреждения будут так же экспортированы как подавленные.
При экспортировании снимка где есть подавленные предупреждения, сами предупреждения будут так же экспортированы как подавленные.
 
=== Поддержка протокола LDAP для аутентификации пользователей ===
=== Поддержка протокола LDAP для аутентификации пользователей ===
====  Общий принцип аутентификации ====
====  Общий принцип аутентификации ====
Line 172: Line 179:
# Сервер запускается с указанием конфигурационного файла с настройками для LDAP аутентификации
# Сервер запускается с указанием конфигурационного файла с настройками для LDAP аутентификации
# В форме аутентификации пользователь выбирает нужный тип аутентификации (svacer или LDAP)  
# В форме аутентификации пользователь выбирает нужный тип аутентификации (svacer или LDAP)  
# При выборе аутентификации LDAP, после заполнения необходимых параметров, запрос на аутентификацию отправляется на сервер svacer
# При выборе аутентификации LDAP, после заполнения необходимых параметров, запрос на аутентификацию отправляется на сервер Svacer
# Сервер Svacer, используя настройки из конфигурационного файла, обращается к внешнему LDAP серверу и проводит проверку пользователя
# Сервер Svacer, используя настройки из конфигурационного файла, обращается к внешнему LDAP серверу и проводит проверку пользователя
# В случае успешной аутентификации, в БД сервера Svacer создается запись (если ее еще нет) для пользователя, чтобы можно было управлять ролями данного пользователя
# В случае успешной аутентификации, в БД сервера Svacer создается запись (если ее еще нет) для пользователя, чтобы можно было управлять ролями данного пользователя
Line 185: Line 192:
Сервер может быть запущен как в с поддержкой аутентификации через LDAP, так и без. Для того, чтобы включить аутентификацию через LDAP необходимо указать конфигурационный файл. Типовой пример конфигурационного файла для подключения к контроллеру домена MS ActiveDirectory или серверу openLDAP можно получить с помощью команды:
Сервер может быть запущен как в с поддержкой аутентификации через LDAP, так и без. Для того, чтобы включить аутентификацию через LDAP необходимо указать конфигурационный файл. Типовой пример конфигурационного файла для подключения к контроллеру домена MS ActiveDirectory или серверу openLDAP можно получить с помощью команды:


    svacer ldap print
  svacer ldap print


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


    svacer server --ldap ldap.json
  svacer server --ldap ldap.json


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


Пример:  
Пример:  
    svacer server --ldap ldap.json --disable-svacer-auth
  svacer server --ldap ldap.json --disable-svacer-auth


====  Конфигурационный файл сервера для поддержки LDAP  ====
====  Конфигурационный файл сервера для поддержки LDAP  ====
Типовой пример конфигурации представлен ниже.
Типовой пример конфигурации:
 
  {
     {
     "servers": [
      "servers": [
      {
        {
        "name": "active_directory",
          "name": "active_directory",
        "basedn": "dc=domain,dc=home,dc=org",
          "basedn": "dc=domain,dc=home,dc=org",
        "useGroup": true,
          "useGroup": true,
        "hideURL": true,
          "hideURL": true,
        "checkAlivePeriod": 60,
          "checkAlivePeriod": 60,
        "connection": {
          "connection": {
          "url": "ldaps://192.168.11.71:636",
            "url": "ldaps://192.168.11.71:636",
          "mirrors":["ldaps://192.168.11.72:636","ldaps://192.168.11.73: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",
            "connectAs": "cn=ldap_service,cn=users,dc=domain,dc=home,dc=org",
          "password": "12345678",
            "password": "12345678",
          "ignoreCertCheck": false,
            "ignoreCertCheck": false,
          "caCertFiles":["/etc/ssl/certs/a*","/etc/ssl/certs/my_certs/*"]
            "caCertFiles":["/etc/ssl/certs/a*","/etc/ssl/certs/my_certs/*"]
        },
          },
        "group": {
          "group": {
          "basedn": "cn=users",
            "basedn": "cn=users",
          "filter": "(&(objectCategory=Group)(cn=dep_devops))",
            "filter": "(&(objectCategory=Group)(cn=dep_devops))",
          "userMember": "member",
            "userMember": "member",
          "display":"cn",
            "display":"cn",
          "svacerRole":"cn"
            "svacerRole":"cn"
        },
          },
        "user": {
          "user": {
          "basedn": "cn=users",
            "basedn": "cn=users",
          "filter": "(&(objectCategory=Person)(sAMAccountName=*))",
            "filter": "(&(objectCategory=Person)(sAMAccountName=*))",
          "login": "sAMAccountName",
            "login": "sAMAccountName",
          "group": "dn",
            "group": "dn",
          "info": {
            "info": {
            "display": "cn",
              "display": "cn",
            "email": "email",
              "email": "email",
            "firstName": "givenName",
              "firstName": "givenName",
            "lastName": "sn"
              "lastName": "sn"
          }
            }
        },
           },
        "enabled": true
           "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": "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
        }
      ]
    }


В конфигурации можно указать несколько серверов. Все сервера в совокупности рассматриваются как единый источник проверки пользователей. То есть если на двух серверах будут два пользователя с одинаковым логином, они будут считаться идентичными. Ниже приводится описание параметров конфигурации.  
В конфигурации можно указать несколько серверов. Все сервера в совокупности рассматриваются как единый источник проверки пользователей. То есть если на двух серверах будут два пользователя с одинаковым логином, они будут считаться идентичными. Ниже приводится описание параметров конфигурации.  
Line 284: Line 290:
* basedn — DN относительно которого будут проводится все операции в LDAP каталоге  
* basedn — DN относительно которого будут проводится все операции в LDAP каталоге  
* useGroup — проверять ли принадлежность пользователя к группе  
* useGroup — проверять ли принадлежность пользователя к группе  
* hideURL — не передавать сетевой адрес LDAP сервера. Конечные пользователи будут видеть в выпадающем списке только имя сервера, указанное в поле name. В поле URL будет пустая строка.
* hideURL — не передавать сетевой адрес LDAP сервера. Конечные пользователи будут видеть в выпадающем списке только имя сервера, указанное в поле name. В поле URL будет пустая строка
* checkAlivePeriod — Промежуток времени в секундах, который должен проходить между периодическими проверками доступности сервера LDAP. Если параметр равен 0 или не указан, такая проверка не проводится.
* checkAlivePeriod — Промежуток времени в секундах, который должен проходить между периодическими проверками доступности сервера LDAP. Если параметр равен 0 или не указан, такая проверка не проводится.
* connection — подсекция, описывающая параметры соединения с сервером  
* connection — подсекция, описывающая параметры соединения с сервером  
:* url — адрес сервера, формата: ldap[s]://domain:port В случае использования TLS для подключения к LDAP серверу, необходимо указать правильный порт (по умолчанию 636).
:* url — адрес сервера, формата: ldap[s]://domain:port В случае использования TLS для подключения к LDAP серверу, необходимо указать правильный порт (по умолчанию 636)
:* mirrors — список хостов, которые будут использованы в случае недоступности основного хоста, указанного в поле URL. Формат указания хостов тот же, что и в поле URL. Префикс ldap[s] должен быть одинаковым для всех хостов и совпадать с префиксом в поле URL.
:* mirrors — список хостов, которые будут использованы в случае недоступности основного хоста, указанного в поле URL. Формат указания хостов тот же, что и в поле URL. Префикс ldap[s] должен быть одинаковым для всех хостов и совпадать с префиксом в поле URL
:* connectAs — имя пользователя в формате DN, из под которого будут производится операции в LDAP каталоге  
:* connectAs — имя пользователя в формате DN, из под которого будут производится операции в LDAP каталоге  
:* password — пароль пользователя  
:* password — пароль пользователя  
:* ignoreCheck — не проверять сертификат в случае ldaps:// соединения. Полезно при самоподписанных сертификатах. Если флаг установлен в значение false, необходимо установить значение поля caCertFiles.
:* ignoreCheck — не проверять сертификат в случае ldaps:// соединения. Полезно при самоподписанных сертификатах. Если флаг установлен в значение false, необходимо установить значение поля caCertFiles
:* CaCertFiles — массив значений, описывающих какие файлы корневых сертификатов добавлять в конфигурацию Svacer. Формат файлов сертификатов — PEM
:* CaCertFiles — массив значений, описывающих какие файлы корневых сертификатов добавлять в конфигурацию Svacer. Формат файлов сертификатов — PEM
* group — подсекция, описывает параметры проверки принадлежности пользователя к группе  
* group — подсекция, описывает параметры проверки принадлежности пользователя к группе  
Line 298: Line 304:
:* userMember — атрибут в группе, содержащий пользователей, принадлежащих группе  
:* userMember — атрибут в группе, содержащий пользователей, принадлежащих группе  
:* display — атрибут, содержащий имя группы для отображения  
:* display — атрибут, содержащий имя группы для отображения  
:* svacerRole — атрибут, из которого будет извлечено имя роли, созданной в Svacer, и автоматически сопоставляемой с пользователем.
:* svacerRole — атрибут, из которого будет извлечено имя роли, созданной в Svacer, и автоматически сопоставляемой с пользователем
* user — подсекция, описывает параметры получения информации о пользователе  
* user — подсекция, описывает параметры получения информации о пользователе  
:* basedn — RDN, добавляемая к общей DN. Относительно этого DN производится поиск группы  
:* basedn — RDN, добавляемая к общей DN. Относительно этого DN производится поиск группы  
:* filter — фильтр, используемый при поиске пользователей.
:* filter — фильтр, используемый при поиске пользователей
:* login — атрибут, в котором находится login пользователя.
:* login — атрибут, в котором находится login пользователя
:* group — атрибут в пользователе, на который ссылается атрибут group.userMember (обычно это «dn» пользователя)
:* group — атрибут в пользователе, на который ссылается атрибут group.userMember (обычно это «dn» пользователя)
:* info — подсекция описывающая в каких атрибутах находится информация о пользователе  
:* info — подсекция описывающая в каких атрибутах находится информация о пользователе  
Line 329: Line 335:
:#* выполняется поиск групп в каталоге LDAP со следующими параметрами:
:#* выполняется поиск групп в каталоге LDAP со следующими параметрами:
:#**строка запроса: (&(objectCategory=Group)(cn=dep_devops)) — взято из поля group.filter
:#**строка запроса: (&(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 конфиг файла
:#**начальный узел: cn=users,dc=domain,dc=home,dc=org, где cn=users — взято из поля group.basedn; значение dc=domain,dc=home,dc=org — взято из поля basedn конфиг файла
:#**поиск производится по всему поддереву
:#**поиск производится по всему поддереву
:#**определяется список пользователей группы (каждому пользователю соответствует значение атрибута с именем member (взято из поля group.userMember конфиг файла))
:#**определяется список пользователей группы (каждому пользователю соответствует значение атрибута с именем member (взято из поля group.userMember конфиг файла))
Line 343: Line 349:
==== Привязка группы LDAP к роли Svacer ====
==== Привязка группы LDAP к роли Svacer ====
Возможно автоматическое назначение пользователям 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 нужные группы (например 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)
:* Администратор 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 создает роли в Svacer, имеющие в точности такое же название, как значение атрибута, указанного в поле svacerRole конфигурационного файла. В пример можно использовать аттрибут cn и в этом случае необходимо создать роли users и admins
:* Администратор Svacer добавляет в конфигурационный файл в поле svacerRole имя атрибута, по которому будет производится привязка. Для примера выше — строчку svacerRole="cn"
:* Администратор Svacer добавляет в конфигурационный файл в поле svacerRole имя атрибута, по которому будет производится привязка. Для примера выше — строчку svacerRole="cn"
Line 361: Line 367:
Для выполнения некоторых действий в cli с помощью команды svacer требуется аутентификация пользователя. Для аутентификации с помощью ldap сервера необходимо указать в команде кроме имени пользователя и пароля  имя сервера с помощью флага ldap_server (имя сервера регистр-зависимо).  Например:
Для выполнения некоторых действий в 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
  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. Например:
Если флаг 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
  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 серверов можно использовать команду:
Для получения списка поддерживаемых свейсером LDAP серверов используйте команду:


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


Вывод содержит два столбца (имя и URL сервера). В качестве значения для параметра ldap_server необходимо использовать содержимое первого столбца.
Вывод содержит два столбца (имя и URL сервера). В качестве значения для параметра ldap_server необходимо использовать содержимое первого столбца.
Line 381: Line 387:
Также данные пользователей можно обновить с помощью интерфейса командной строки. Для этого можно использовать подкоманду '''updateUsers''' команды '''ldap'''. Общий синтаксис команды выглядит следующим образом:
Также данные пользователей можно обновить с помощью интерфейса командной строки. Для этого можно использовать подкоманду '''updateUsers''' команды '''ldap'''. Общий синтаксис команды выглядит следующим образом:


    ./svacer ldap updateUsers --onlyEmpty
  svacer ldap updateUsers --onlyEmpty


Флаг '''onlyEmpty''' позволяет обновлять только пустые поля ФИО и eMail. Заполненные поля не будут изменены. Команда обновит данные всех пользователей, записи о которых имеются в базе Svacer.  
Флаг '''onlyEmpty''' позволяет обновлять только пустые поля ФИО и eMail. Заполненные поля не будут изменены. Команда обновит данные всех пользователей, записи о которых имеются в базе Svacer.  
Line 392: Line 398:
Пример запуска сервера с поддержкой сквозной аутентификации:
Пример запуска сервера с поддержкой сквозной аутентификации:


    ./svacer server --proxy-mode
  svacer server --proxy-mode


=== Хуки ===
=== Хуки ===
Line 398: Line 404:
Каждый хук соответствует некоторому процессу или скрипту, который сервер запускает в ответ на вызов соответствующей команды из web-интерфейса.
Каждый хук соответствует некоторому процессу или скрипту, который сервер запускает в ответ на вызов соответствующей команды из web-интерфейса.
Формат файла Hooks следующий:
Формат файла Hooks следующий:
    {
  {
      "hooks": [
    "hooks": [
        {
      {
          "id": "<id>",
        "id": "<id>",
          "label": "<label >",
        "label": "<label >",
          "target": "<target>",
        "target": "<target>",
          "input": ["<param1>", "<param2>",],
        "input": ["<param1>", "<param2>", ...],
          "cmd": "<path to executable>",
        "cmd": "<path to executable>",
          "args": ["<arg1>", “<arg2>”, ]
        "args": ["<arg1>", “<arg2>”, ...]
        },
      },
        ...
      ...
      ]
    ]
    }
  }


'''Параметры хуков '''
'''Параметры хуков '''
Line 447: Line 453:
=== Автомиграция разметки ===
=== Автомиграция разметки ===


На svacer возможно настроить автомиграцию разметки с ветки на ветку (необходимо разрешение на администрирование сервера у пользователя).
В Svacer возможно настроить автомиграцию разметки с ветки на ветку (необходимо разрешение на администрирование сервера у пользователя).


    svacer server automigrate [command] [flags]
  svacer server automigrate [command] [flags]


Существующие command:
Существующие command:
* add — добавляет автомиграцию в соответствии с паттерном
* delete — удаляет автомиграцию
* show_config — показывает все заданные миграции (Config Table), их id, время создания и пользователя, который их создал
* show_automigrate — показывает таблицу всех существующих проектов и веток с которых и на которые происходят автоматические миграции (Automigrate Table)
* log — выводит список всех совершенных миграций (Done Automigrate Table)


* add - добавляет автомиграцию в соответствии с паттерном;
Флаг '''pattern''' (применяется для command <code><add|delete|show_config|log></code>):
 
* delete - удаляет автомиграцию;
 
* show_config - показывает все заданные миграции (Config Table), их id, время создания и пользователя, которые её создал;
 
* show_automigrate - показывает таблицу всех существующих проектов и веток с которых и на какие происходят автоматические миграции (Automigrate Table);
 
* log - выводит список всех совершенных миграций (Done Automigrate Table).
 
Флаг '''pattern''' (применяется для command <add|delete|show_config|log>):


* Для add: Паттерн автомиграции формате: srcProject{Id|Name}/srcBranch{Id|Name}=>receiveProject{Id|Name|RegEx}/receiveBranch{Id|Name|RegEx}. RegEx - в формате SIMILAR TO RegEx для PostgreSQL  
* Для add: Паттерн автомиграции в формате: <code>srcProject{Id|Name}/srcBranch{Id|Name}=>receiveProject{Id|Name|RegEx}/receiveBranch{Id|Name|RegEx}</code>. RegEx в формате как для PostgreSQL (https://www.postgresql.org/docs/current/functions-matching.html, пункт 9.7.2).
(https://www.postgresql.org/docs/current/functions-matching.html пункт 9.7.2).


* Для delete: Паттерн автомиграции в формате: srcProject{Id|Name}/srcBranch{Id|Name}=>receiveProject{Id|Name|RegEx}/receiveBranch{Id|Name|RegEx}. Паттерн должен быть точно таким же, каким он записан в Config Table.
* Для delete: Паттерн автомиграции в формате: <code>srcProject{Id|Name}/srcBranch{Id|Name}=>receiveProject{Id|Name|RegEx}/receiveBranch{Id|Name|RegEx}</code>. Паттерн должен быть точно таким же, каким он записан в Config Table


* Для show_config: Паттерн автомиграции. Поиск будет происходить в следующем виде: ILIKE "'%"+pattern+"%'".
* Для show_config: Паттерн автомиграции. Поиск будет происходить в следующем виде: <code>ILIKE "'%"+pattern+"%'"</code>


* Для log: Флаг в формате srcProjectId/srcBranchId=>receiveProjectId/receiveBranchId или srcProjectName/srcBranchName=>receiveProjectName/receiveBranchName для вывода автомиграций с данным паттерном.
* Для log: Флаг в формате <code>srcProjectId/srcBranchId=>receiveProjectId/receiveBranchId</code> или <code>srcProjectName/srcBranchName=>receiveProjectName/receiveBranchName</code> для вывода автомиграций с данным паттерном


Флаг '''id''' (применяется для command <delete|show_automigrate> в формате uuid):
Флаг '''id''' (применяется для command <code><delete|show_automigrate></code> в формате uuid):


* Для delete: id для удаления автомиграции (из Config Table)
* Для delete: id для удаления автомиграции (из Config Table)


* Для show_automigrate: id ветки/проекта или конфигурации для нахождения его в таблице автомиграций (Automigrate Table) и вывода автомиграций,где присутствует данный id.
* Для show_automigrate: id ветки/проекта или конфигурации для нахождения его в таблице автомиграций (Automigrate Table) и вывода автомиграций, где присутствует данный id


Флаг '''format''' (применяется для command <show_config|show_automigrate|log>)
Флаг '''format''' (применяется для command <code><show_config|show_automigrate|log></code>)


* Для show_config: Формат вывода таблицы. Возможные значения: table - вывод в виде таблицы, json - вывод в виде json, no-id - вывод без config id. Значения можно перечислить через запятую: json,no-id. По умолчанию table.
* Для show_config: Формат вывода таблицы.  
:Возможные значения:  
:* table вывод в виде таблицы
:* json вывод в виде json
:* no-id вывод без config id
:Значения можно перечислить через запятую: <code>json,no-id</code>. По умолчанию table.


* Для show_automigrate|log: Формат вывода таблицы. Возможные значения: table - вывод в виде таблицы, json - вывод в виде json. По умолчанию table.
* Для show_automigrate|log: Формат вывода таблицы.  
:Возможные значения:  
:* table вывод в виде таблицы
:* json вывод в виде json
:По умолчанию table.


Также возможно использовать POST запрос по адресу /api/automigrate. В теле передается json, с полями action(not null), pattern, id. Выполняется по тому же принципу, что и CLI.
Также возможно использовать POST запрос по адресу <code>/api/automigrate</code>. В теле передается json, с полями <code>action(not null), pattern, id</code>. Выполняется по тому же принципу, что и CLI.


Принцип работы сервиса:  
Принцип работы сервиса:  
* При запуске сервера запускается сервис automigrate
* При занесении новой миграции, находит все миграции, подходящие под паттерн, и копирует разметку на них
* При удалении миграции, удаляет её из таблицы Config и удаляет из таблицы автомиграций
* Не может копировать разметку с нескольких веток на одну (будет выдавать ошибку)


* При запуске сервера запускается сервис automigrate.
* При любом изменении разметки у существующих веток (добавление/удаление/изменение комментариев, добавление снимка, добавление проекта, добавление ветки, изменение имени ветки/проекта, удаление контейнера, удаление снимка) происходит либо миграция разметки, либо добавление новых миграций в таблицу автомиграций и миграция разметки, либо удаление миграции из таблицы автомиграций (в зависимости от конкретной ситуации). При какой-либо ошибке выдает предупреждение, но даёт выполнить действие.
 
* При занесении новой миграции, находит все миграции, подходящие под паттерн, и копирует разметку на них.
 
* При удалении миграции, удаляет её из таблицы Config и удаляет из таблицы автомиграций.
 
* Не может копировать разметку с нескольких веток на одну (будет выдавать ошибку).
 
* При любом изменении разметки у существующих веток (добавлен/удаление/изменение комментариев, добавление снэпшота, добавление проекта, добавление ветки, изменение имени ветки/проекта, удаление контейнера, удаление снэпшота) происходит либо миграция разметки, либо добавление новых миграций в таблицу автомиграций и миграция разметки, либо удаление миграции из таблицы автомиграций (в зависимости от конкретной ситуации). При какой-либо ошибке выдает предупреждение, но даёт выполнить действие.


* Единственный случай, когда не даёт выполнить действие - это upload результатов svace через CLI (либо import с флагом --upload). Тогда выдает ошибку миграции и отменяет upload (может произойти, когда имя данной ветки (в качестве to_branch) подходит под несколько паттернов).
* Единственный случай, когда не даёт выполнить действие это загрузка результатов Svace через CLI (upload, либо import с флагом --upload). Тогда выдает ошибку миграции и отменяет загрузку (может произойти, когда имя данной ветки (в качестве to_branch) подходит под несколько паттернов).

Revision as of 19:09, 14 November 2023

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

Запустив Svacer без параметров, можно получить информацию о доступных командах. Дополнительная информация о каждой команде доступна при использовании опции --help

 svacer <command name> --help

Общий формат командной строки

 svacer [global options] command [command options] [arguments...]

Глобальные опции относятся ко всем командам. Опции команд имеют префикс «--». Их следует указывать до списка аргументов. Для команд с опцией --password доступна возможность ввода пароля с клавиатуры.

Создание PDF отчета для проекта

Для создания PDF отчета по проекту из интерфейса командной строки используется команда pdfgen. Назначение команды состоит в том, чтобы добиться из консоли результатов (создание PDF файла отчета), аналогичным следующим действиям пользователя в GUI:

  1. Выгрузка таблицы маркеров в формате PDF (Рис. 1)
  2. Предварительное формирование содержимого таблицы маркеров
    • По режимам сравнения (new, missing, same, matched) с указанием цели и источника сравнения, (Рис. 2)
    • По используемым фильтрам Custom (ограниченный набор из 4 параметров) (Рис. 3)

Ниже приводятся фрагменты GUI, которым соответствует cli команда в различных вариантах ее использования:

SimpleReport window

Рис. 1 — Отчет без сравнения

CompareReport window

Рис. 2 — Отчет со сравнением

CompareFiltersReport window

Рис. 3 — Отчет со сравнением и фильтрами

Общий вид команды следующий:

 svacer pdfgen --cmpMode [none|new|missing|matched|same] --project [name|id] --branch [name|id] --snapshot [name|id] [--targetProject [name|id] --targetBranch [name|id] --targetSnapshot [name|id]] [--file [re_exp] --checker [re_exp] --severity [re_exp] --review [re_exp]] --outFile report_name --tz time_zone --lang report_lang

Описание параметров:

  • cmpMode — параметры сравнения. Возможные значения: none — без сравнения, new — новые, missing — отсутствующие, matched — сопоставленные, same — одинаковые
  • Project, Branch, Snapshot — параметры, описывающие снимок, отчет для которого требуется создать. В качестве значений могут использоваться как имена, так и идентификаторы соответствующих сущностей. Например: --project zstd --branch "7683ed6a-b838-4090-9945-10e148f94be3" --snapshot zstd_130
  • targetProject, targetBranch, targetSnapshot — параметры, описывающие снимок, с которым необходимо провести сравнение (обязательные параметры для режимов cmpMode: new, missing, matched, same).
  • File, checker, severity, review — параметры, задающие фильтры, применяемые к списку маркеров. Фильтры задают условия включения маркера в отчет. Значения фильтров задаются в формате регулярных выражений. В случае неверного формата, ошибочный фильтр не будет применяться и операция экспорта будет выполнена, как если бы фильтр не был указан. File — фильтр по пути к файлу, где был обнаружен маркер. Checker — фильтр по чекеру, предупреждение от которого было создано. Severity — серьезность сработавшего чекера. Review — статус разметки (confirmed, unclear и т.д.)
  • outFile — имя создаваемого файла отчета. Если не будет указано расширение, будет добавлено расширение pdf
  • tz — временная зона в минутах. Используется при формировании записи о комментариях, которые оставил пользователь, производивший разметку
  • lang — язык, который будет использован в создаваемом отчете (en — английский, ru — русский)

Для создания отчета без использования режима сравнения, необходимо указать cmpMode в значение none (это значение используется по умолчанию). Для предварительного формирования таблицы маркеров с учетом сравнения, использовать значения cmpMode [new, missing, same, matched]. Названия этих режимов аналогичны названиями в GUI. При этом требуется указание как минимум одного параметра из списка: targetProject, targetBranch, targetSnapshot. Если какие-то параметры target* не указаны, они будут установлены в значение исходных (project → targetProject, branch → targetBranch, ...). Сформированные на предварительном этапе маркеры, проходят механизм фильтраций (параметры: severity, file, review, checker), после чего происходит создание отчета.

Для создания отчета можно также использовать public API. Необходимо использовать следующие параметры:

URL — /api/public/exportPDF
Метод — POST

Тело запроса — формат JSON, имеет следующий вид:

   {
   "compare_mode": "new",
   "context":{
     "project": "zstd",
     "branch": "v13",
     "snapshot": "zstd_131"
    },
   "target_context":{
     "project": "zstd",
     "branch": "v13",
     "snapshot": "zstd_132"
    },
    "language": "en",
    "timezone": 180,
    "filters": {
      "checker": "^Z.*$",
      "file": ".*example.*",
      "severity": "Cr.*",
      "review": "Conf.*"
    } 
   }

Данный запрос соответствует запросу на создание отчета, который получается в результате сравнения в рамках проекта zstd и ветки v13 двух снимков zstd_131 и zstd_132. При этом будут выбраны только новые маркеры. Среди выбранных останутся только те, что удовлетворяют условиям фильтров, а именно: чекер начинается с буквы Z, файл содержит слово example, серьезность чекера содержит подстроку Cr (что в силу ограниченного количества значений для данного фильтра соответствует значению Critical) в названии, а состояние разметки содержит подстроку Conf (что в силу ограниченного количества значений для данного фильтра соответствует значению Confirmed). Язык отчета — английский, часовой пояс — 180 минут (3 часа).

Импорт разметки из исходного кода на сервер истории

Импорт разметки из исходного кода на сервер истории возможен с помощью команды svacer markup import.

Синтаксис:

 svacer markup --user <user> --password <password> --project <project id or name> --branch <branch id or name> --snapshot <snapshot id or name> import --template <name> [--excludePaths <path1, path2, ... ,pathN> --from-build-object]

Где:

  • user, password — пользователь и пароль учетной записи на сервере истории
  • project — проект на сервере истории, в который будет произведен импорт разметки
  • branch — ветка в проекте выбранном выше (по умолчанию master), в которую будет произведен импорт разметки
  • snapshot — снимок в выбранных проекте и ветке (по умолчанию последний загруженный), в который будет произведен импорт разметки
  • excludePaths — исключает файлы, соответствующие регулярным выражениям
  • template — определяет имя шаблона для импорта разметки (важно: флаг обязательный, в отличие от экспорта)
  • from-build-object — при включении этой опции, разметка будет выгружаться из объекта сборки того снимка, который был указан в опциях выше.

После выполнения команды все комментарии оставленные в коде в соответствии с выбранным шаблоном разметки будут разобраны и добавлены на сервер истории в соответствующий проект/ветку/снимок.

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

 //svacer_review: -<warn class>[|-<warn class>]+ 

Пример:

 if (!strncmp("--filelimit",argv[i],11)) {
   j = 11; //svacer_review: -UNUSED_VALUE
   if (*(argv[i]+11) == '=') {

Комментарий должен быть расположен в конце строки, где ожидается предупреждение от анализатора Svace.

Для импорта разметки при использовании команд import --upload и upload следует указывать флаг --template <template>. В таком случае разметка будет импортирована из объекта сборки сразу после загрузки его на сервер.

Описание шаблона разметки DEFAULT

Сервер позволяет добавить собственные шаблоны разметки, для удобства добавлен неудаляемый шаблон DEFAULT. Список шаблонов можно увидеть в Settings > Markup templates (при наличии у пользователя доступа).

Шаблон можно использовать как для импорта, так и для экспорта разметки, поэтому можно проверить ожидаемый формат через выгрузку кода с указанием шаблона.

В шаблоне DEFAULT каждая разметка описывается на отдельной строчке перед маркером, при необходимости можно использовать несколько строчек. Импорт разметки с неправильным статусом или со статусом Undecided не производится, включая комментарий.

Пример:

 //svacer_review: FORMAT_STRING.PARAM_EXCESS r:Confirmed|s:Minor|a:Undecided|c:
 //svacer_review: UNINIT.LOCAL_VAR r:Confirmed|s:Unspecified|a:Fix required|c:will be fixed
 printf("v = %d", fl3(), i);

Разметка нескольких одинаковых предупреждений на одной строчке проблематична, гарантируется только что разметка будет применена к маркеру с таким названием.

Изменение инвариантов для распространения разметки между снимками с несовпадающими путями

Если на сервер был загружен снимок, в котором расположение некоторых (или всех) файлов поменялось, а при импорте не был указан флаг --pathPrefix, то разметка с прошлого снимка не распространится на новый снимок. Для решения данной проблемы следует использовать команду svacer markup update.

Синтаксис:

 svacer markup update --user <user> --password <password> --project <project id or name> --branch <branch id or name> --pathPrefix <prefix:replacement; prefix:replacement> [<snapshot id or name>1, <snapshot id or name>2, ..., <snapshot id or name>N]

Где:

  • user, password — пользователь и пароль учетной записи на сервере истории
  • project — проект на сервере истории, в котором будет обновлена разметка
  • branch — ветка в проекте выбранном выше (по умолчанию master), в которой будет обновлена разметка
  • pathPrefix — правило отображения для префиксов путей в формате: <file> или line prefix:replacement;prefix:replacement

В конце команды опционально могут быть указаны имена или идентификаторы снимков, в которых будет обновлена разметка в соответствии с указанными префиксами путей. Если они указаны не будут, изменения будут применены ко всей ветке. После запуска команды на сервер будет отправлен асинхронный запрос на обновление разметки, за дальнейшим прогрессом исполнения можно следить в логе сервера (через UI он доступен пользователям с ролью admin в Settings > Server information).

Подавление предупреждений

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

Список подавленных предупреждений (печатает JSON)

 svacer markup [auth/selection] suppress list

Пример

 svacer markup --user admin --password admin --project tree-command suppress list


Подавить предупреждение

 svacer markup [auth/selection] suppress add id1 id2 id3

Пример

 svacer markup --user admin --password admin --project tree-command suppress add 29d298cd-752d-4d19-b535-2089a72a96af


Убрать подавление предупреждения

 svacer markup [auth/selection] suppress remove id1 id2 id3

Пример

 svacer markup --user admin --password admin --project tree-command suppress remove 29d298cd-752d-4d19-b535-2089a72a96af


Убрать все подавления

 svacer markup [auth/selection] suppress remove

Пример

 svacer markup --user admin --password admin --project tree-command suppress remove

Список предупреждений с ID доступен посредством public REST API. Функциональность предназначена для интеграции со сторонними инструментами и встраивания в CI/CD pipeline. На текущий момент информация о подавленных предупреждениях недоступна в веб-интерфейсе.

При экспортировании снимка где есть подавленные предупреждения, сами предупреждения будут так же экспортированы как подавленные.

Поддержка протокола 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

Хуки

Для получения данных хуков при запуске сервера нужно указать опцию --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>”, ...]
     },
     ...
   ]
 }

Параметры хуков

Параметр Описание
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. Примеры скриптов для этого можно найти на странице Примеры использования хуков.

Автомиграция разметки

В Svacer возможно настроить автомиграцию разметки с ветки на ветку (необходимо разрешение на администрирование сервера у пользователя).

 svacer server automigrate [command] [flags]

Существующие command:

  • add — добавляет автомиграцию в соответствии с паттерном
  • delete — удаляет автомиграцию
  • show_config — показывает все заданные миграции (Config Table), их id, время создания и пользователя, который их создал
  • show_automigrate — показывает таблицу всех существующих проектов и веток с которых и на которые происходят автоматические миграции (Automigrate Table)
  • log — выводит список всех совершенных миграций (Done Automigrate Table)

Флаг pattern (применяется для command <add|delete|show_config|log>):

  • Для delete: Паттерн автомиграции в формате: srcProject{Id|Name}/srcBranch{Id|Name}=>receiveProject{Id|Name|RegEx}/receiveBranch{Id|Name|RegEx}. Паттерн должен быть точно таким же, каким он записан в Config Table
  • Для show_config: Паттерн автомиграции. Поиск будет происходить в следующем виде: ILIKE "'%"+pattern+"%'"
  • Для log: Флаг в формате srcProjectId/srcBranchId=>receiveProjectId/receiveBranchId или srcProjectName/srcBranchName=>receiveProjectName/receiveBranchName для вывода автомиграций с данным паттерном

Флаг id (применяется для command <delete|show_automigrate> в формате uuid):

  • Для delete: id для удаления автомиграции (из Config Table)
  • Для show_automigrate: id ветки/проекта или конфигурации для нахождения его в таблице автомиграций (Automigrate Table) и вывода автомиграций, где присутствует данный id

Флаг format (применяется для command <show_config|show_automigrate|log>)

  • Для show_config: Формат вывода таблицы.
Возможные значения:
  • table — вывод в виде таблицы
  • json — вывод в виде json
  • no-id — вывод без config id
Значения можно перечислить через запятую: json,no-id. По умолчанию — table.
  • Для show_automigrate|log: Формат вывода таблицы.
Возможные значения:
  • table — вывод в виде таблицы
  • json — вывод в виде json
По умолчанию — table.

Также возможно использовать POST запрос по адресу /api/automigrate. В теле передается json, с полями action(not null), pattern, id. Выполняется по тому же принципу, что и CLI.

Принцип работы сервиса:

  • При запуске сервера запускается сервис automigrate
  • При занесении новой миграции, находит все миграции, подходящие под паттерн, и копирует разметку на них
  • При удалении миграции, удаляет её из таблицы Config и удаляет из таблицы автомиграций
  • Не может копировать разметку с нескольких веток на одну (будет выдавать ошибку)
  • При любом изменении разметки у существующих веток (добавление/удаление/изменение комментариев, добавление снимка, добавление проекта, добавление ветки, изменение имени ветки/проекта, удаление контейнера, удаление снимка) происходит либо миграция разметки, либо добавление новых миграций в таблицу автомиграций и миграция разметки, либо удаление миграции из таблицы автомиграций (в зависимости от конкретной ситуации). При какой-либо ошибке выдает предупреждение, но даёт выполнить действие.
  • Единственный случай, когда не даёт выполнить действие — это загрузка результатов Svace через CLI (upload, либо import с флагом --upload). Тогда выдает ошибку миграции и отменяет загрузку (может произойти, когда имя данной ветки (в качестве to_branch) подходит под несколько паттернов).