Help:Installation: Difference between revisions

From Svacer Wiki
VisualWikitext
No edit summary
(bump recommended postgres version)
 
(84 intermediate revisions by 6 users not shown)
Line 1: Line 1:
[[Category:Help]]
[[Category:Help]]
[[:Category:Help]]
== Установка и запуск ==
__TOC__
Для использования только клиента Svacer достаточно [[Svacer#Релизы|скачать исполняемый файл]] '''svacer''' (или установить deb/rpm пакет).


Для запуска сервера Svacer установите пакеты, указанные в [[Help:Installation#Requirements|requirements]], после чего [[Help:Installation#Установка_и_запуск_из_deb/rpm_пакета|установите сервер]], [[Help:Installation#Создание БД и запуск сервера Svacer|создайте БД и запустите его]].


== Установка ==
=== Requirements ===
Для работы сервера необходим PostgreSQL. Его можно установить как пакет, либо запустить в докере — docker-compose файл для этого находится в '''./extra/docker-compose-postgres.yml'''.
==== PostgreSQL ====
Svacer сервер состоит из единственного бинарного файла — '''svacer'''. Он предоставляет как backend-часть, так и веб-сервер, который передаёт статику. По умолчанию запускается на порту 8080.
Для работы сервера Svacer установите (или [[Help:Installation#Запуск в docker|запустите в докере]]) PostgreSQL версии не ниже 14-й, следуя [https://www.postgresql.org/download/linux документации postgres].
После запуска по умолчанию создается учётная запись пользователя '''admin''' c паролем '''admin'''. Изменить пароль можно в веб-интерфейсе.
Сервер имеет широкие возможности настройки параметров запуска. Узнать о них подробнее можно, прочитав '''svacer --help'''.


=== Установка и запуск из deb/rpm пакета ===
На Debian-based системах, обычно, достаточно выполнить команду
Процесс установки из .deb и .rpm пакетов несколько различается и будет описан ниже в отдельных главах. Процесс настройки и запуска не различается и будет описан в одной общей главе.
 
  sudo apt install postgresql
 
Для RedHat-based ОС также установите пакет postgresql-contrib. Пример для Centos 7:
 
<pre>
  sudo yum install -y https://download.postgresql.org/pub/repos/yum/reporpms/EL-7-x86_64/pgdg-redhat-repo-latest.noarch.rpm
  sudo yum install -y postgresql14-server postgresql14-contrib
  sudo /usr/pgsql-14/bin/postgresql-14-setup initdb
  sudo systemctl enable postgresql-14
  sudo systemctl start postgresql-14
</pre>
 
Для версий PostgreSQL ниже 13-й требуется явно разрешить подключение к локальному хосту базы с логином/паролем. Для этого проверьте следующие строчки в конце файла '''/var/lib/pgsql/<version>/data/pg_hba.conf'''
 
  # IPv4 local connections:
  host    all    all    127.0.0.1/32    ident<br>
  # IPv6 local connections:
  host    all    all    ::1/128        ident
 
Если в последнем столбце указано значение '''ident''', поменяйте его на '''md5''' и перезапустите PostgreSQL.
 
  sudo systemctl restart postgresql-12
 
===== Запуск PostgreSQL в docker =====
Можно запустить PostgreSQL в докер-контейнере. Используйте файл [https://svacer.ispras.ru/extra/docker-compose-postgres.yml docker-compose-postgres.yml]
 
  docker-compose -f docker-compose-postgres.yml up -d


Чтобы остановить, соответственно


==== .deb ====
  docker-compose -f docker-compose-postgres.yml down
Скачайте .deb пакет релиза и выполните следующую команду


    sudo apt install ./svacer_<version>_amd64.deb
При таком способе запуска создается пользователь и база, указанные в Svacer как параметры по умолчанию, поэтому при запуске сервера Svacer параметр '''--pg''' можно не указывать (и не менять в конфиг-файле '''/etc/default/svacer''' при установке Svacer из пакетов).


При этом, если в репозиториях есть PostgreSQL нужной версии, он будет установлен автоматически. Если нет, то установка завершится с ошибкой о зависимости от PostgreSQL. В этом случае вам надо будет установить PostgreSQL версии не ниже 10-й (см. [https://www.postgresql.org/download/linux/ документацию]), после чего повторить установку Svacer.
==== Браузер для PDF-отчетов ====
При запуске Svacer проверяет доступность браузера для генерации PDF. Если он не установлен или генерация не работает, будет использован нативный генератор: менее продвинутый, но для него не нужен браузер. Можно явно включить использование нативного генератора, передав опцию <code>--pdf-generator=native</code> при запуске сервера Svacer.


Для создания PDF-отчетов с использованием нового HTML-генератора установите браузер Google Chrome на машину, где запускается сервер Svacer.


==== .rpm ====
Рекомендуется устанавливать из официального deb- или rpm-пакета, следуя [https://www.google.com/chrome/?platform=linux инструкции с сайта google].  
Установите PostgeSQL версии не ниже 10-й для вашей ОС следуя [https://www.postgresql.org/download/linux/redhat/ документации]. Дополнительно установите пакет postgresql-contrib из тех же репозиториев.


При невозможности установить Google Chrome, например если нет пакета для вашего дистрибутива Linux, можно установить Chromium. Его пакет в репозиториях, в зависимости от вышей ОС, может называться <code>chromium-browser</code> или <code>chromium</code>.


Пример для Centos 7<br>
  sudo apt install chromium-browser
  sudo apt install chromium


    sudo yum install -y https://download.postgresql.org/pub/repos/yum/reporpms/EL-7-x86_64/pgdg-redhat-repo-latest.noarch.rpm
На RedHat-based ОС
    sudo yum install -y postgresql14-server postgresql14-contrib
    sudo /usr/pgsql-14/bin/postgresql-14-setup initdb
    sudo systemctl enable postgresql-14
    sudo systemctl start postgresql-14


Для версий PostgreSQL ниже 13-й требуется явно разрешить подключение к локальному хосту базы с логином/паролем. Для этого проверьте следующие строчки в конце файла '''/var/lib/pgsql/<version>/data/pg_hba.conf'''
  sudo yum install chromium


    # IPv4 local connections:
В некоторых случаях генерация с Chromium может не работать. Например, если Svacer установлен из deb-пакета, а Сhromium из snap (на Ubuntu он устанавливается именно так даже при использовании apt) и сервер Svacer запускается от отдельного системного пользователя, от которого Chromium не может запуститься. В этом случае установите Google Chrome, с ним генерация работает.
    host    all    all    127.0.0.1/32    ident<br>
    # IPv6 local connections:
    host    all    all    ::1/128        ident


В случае если в последнем столбце указано значение '''ident''', поменяйте его на '''md5''' и перезапустите PostgreSQL.
=== Установка и запуск из deb/rpm пакета ===
При установке из deb- или rpm-пакета Svacer ставится в директорию, прописанную в $PATH, поэтому при запуске полный путь к исполняемым файлам указывать не требуется, они будут доступны по имени.


    sudo systemctl restart postgresql-12
==== deb ====
Добавьте apt-репозиторий и установите Svacer из него.


Скачайте .rpm пакет релиза Svacer и выполните следующую команду
<pre>
echo 'deb [signed-by=/usr/share/keyrings/ispras.gpg] https://repo.ispras.ru/apt /' | sudo tee /etc/apt/sources.list.d/ispras.list
curl -fsSL https://repo.ispras.ru/apt/key.asc | sudo gpg --dearmor -o /usr/share/keyrings/ispras.gpg
sudo apt update
sudo apt install -y svacer
</pre>


    sudo yum install ./svacer-<version>.x86_64.rpm
Если нет доступа к репозиторию, можно скачать deb-пакет и установить следующей командой


  sudo apt install ./svacer_<version>_amd64.deb


==== Настройка и запуск ====
==== rpm ====
Процесс настройки и запуска одинаковый для Svacer установленного из .deb и .rpm пакетов.
Добавьте dnf/yum-репозиторий и установите Svacer из него


<pre>
curl -fsSL https://repo.ispras.ru/rpm/ispras.repo | sudo tee /etc/yum.repos.d/ispras.repo
sudo dnf install svacer
</pre>


В процессе установки создаются следующие файлы и директории
Если нет доступа к репозиторию, можно скачать rpm-пакет и установить следующей командой
* /etc/default/svacer — конфигурационный файл
* /var/log/svacer — директория для логов
* /var/lib/svacer — директория для object store


sudo dnf install ./svacer-<version>.x86_64.rpm


После установки Svacer требуется создать пользователя и БД PostgreSQL. Для этого перейдите в пользователя postgres, запустите psql и выполните соответствующие запросы, после чего выйдите из консоли PostgreSQL и из пользователя postgres.
==== Создание БД и запуск сервера Svacer ====
Для создания БД PostgreSQL запустите '''psql''' от учетной записи пользователя '''postgres''' и выполните соответствующие запросы:


    sudo su -l postgres
  sudo su -l postgres
    psql
  psql
    postgres=# create database svace;
  postgres=# create database svace;
    postgres=# create user svace with encrypted password 'svace';
  postgres=# create user svace with encrypted password 'svace';
    postgres=# grant all privileges on database svace to svace;
  postgres=# grant all privileges on database svace to svace;
    postgres=# alter user svace superuser;
  postgres=# alter user svace superuser;


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


При использовании других имен пользователя, БД или пароля потребуется дополнительная конфигурация перед запуском Svacer: в файле '''/etc/default/svacer''' нужно поменять параметры подключения к БД в строке
При использовании других имен пользователя, БД или пароля нужно поменять параметры подключения к БД в файле '''/etc/default/svacer'''


    SVACER_ARGS="--pg postgres://<user>:<password>@127.0.0.1:5432/<database>"
  SVACER_ARGS="--pg postgres://<user>:<password>@127.0.0.1:5432/<database>"


В этой же строке можно указывать прочие аргументы для запуска сервера Svacer.
В этой же строке можно указать прочие аргументы для запуска сервера Svacer.


На Astra Linux необходимо в файле '''/etc/parsec/mswitch.conf''' установить параметр <code>zero_if_notfound: yes</code>, иначе при запуске Svacer будет ошибка подключения к БД вида


После создания БД и настройки конфигурации Svacer запустить его можно следующими командами
  error obtaining MAC configuration for user "svace" (SQLSTATE 57P03)


    sudo systemctl enable svacer
После создания БД и конфигурации сервера Svacer запустить его можно следующими командами
    sudo systemctl start svacer
 
  sudo systemctl enable svacer
  sudo systemctl start svacer


После чего проверить успешность запуска командой
После чего проверить успешность запуска командой


    systemctl status svacer
  systemctl status svacer


В случае успешного запуска сервер будет доступен по адресу http://localhost:8080
В случае успешного запуска сервер будет доступен по адресу http://localhost:8080, логин / пароль — admin / admin.


=== Запуск в docker ===
Установите docker и docker-compose. Образы PostgreSQL и Svacer размещены на докерхабе, поэтому для их скачивания при запуске нужен интернет.
Используйте для запуска файл [https://svacer.ispras.ru/extra/docker-compose.yml docker-compose.yml]. Перейдите в директорию, где находится этот файл, и выполните команду
docker-compose up -d


При установке из .deb или .rpm пакета Svacer ставится в директорию, прописанную в $PATH, поэтому при запуске Svacer для импорта и загрузки результатов полный путь к исполняемому файлу '''svacer''' указывать не требуется, он будет доступен просто по имени.
Запустятся два контейнера: PostgreSQL и Svacer. Веб-интерфейс Svacer будет доступен по адресу http://localhost:8080, логин / пароль — admin / admin


В процессе запуска будут созданы два [https://docs.docker.com/storage/volumes/ docker volume] для сохранения данных после остановки или перезапуска контейнеров.


=== Запуск в docker ===
* svacer-postgres — для БД PostgreSQL
Установите docker и docker-compose. Поскольку образы PostgreSQL и Svacer размещены на докер-хабе, для их скачивания при запуске необходимо наличие интернета.
* svacer-object-store — для object store сервера Svacer
 
Чтобы остановить сервер Svacer выполните следующую команду
 
docker-compose down
 
Для сборки своего докер-образа Svacer можете использовать [[Dockerfile]] в качестве референса.
 
=== Установка и запуск вручную ===
Запустите '''svacer-server''' из консоли с указанием параметров подключения к БД:
 
* Если при создании пользователя и БД PostgreSQL вы использовали для них имя по умолчанию 'svace', как в примере выше, то указывать данные для подключения к БД при запуске сервера не обязательно
  ./svacer-server run
* Если создавали пользователя или БД с другими именами, то при запуске сервера надо указать их явно
  ./svacer-server run --pg postgres://svacer_user:svacer_password@127.0.0.1:5432/svacer_database
 
После запуска сервера его веб-интерфейс будет доступен по адресу http://localhost:8080, логин / пароль — admin / admin
 
=== Установка и запуск на Windows ===
Далее будут описаны шаги установки и запуска сервера Svacer. Для использования только клиента Svacer установка и настройка PostgreSQL не требуется.
* Скачайте установщик PostgreSQL для Windows: https://www.postgresql.org/download/windows
* Установите PostgreSQL, выбрав, как минимум, компоненты "PostgreSQL Server" и "Command Line Tools"
* Задайте и запомните пароль на шаге выбора пароля для суперпользователя
* Остальные параметры при установке можно оставить по умолчанию
* После установки PostgreSQL откройте консоль, перейдите в директорию, куда установили PostgreSQL, запустите его клиент с указанием пользователя "postgres" и авторизуйтесь с паролем, заданным во время установки
  cd c:\Program Files\PostgreSQL\15\bin
  psql -U postgres
* Запустится консоль управления PostgreSQL. Выполните в ней следующие команды, чтобы создать БД и пользователя для Svacer
  create database svace;
  create user svace with encrypted password 'svace';
  grant all privileges on database svace to svace;
  alter user svace superuser;
* Выйдите из консоли PostgreSQL
* Запустите '''svacer-server.exe''' из консоли с указанием параметров подключения к БД. Если при создании пользователя и БД PostgreSQL вы использовали для них имя по умолчанию 'svace', как в примере выше, то указывать данные для подключения к БД при запуске сервера не обязательно
  svacer-server.exe run
* Если создавали пользователя или БД с другими именами, то при запуске сервера надо указать их явно
  svacer-server.exe run --pg postgres://svacer_user:svacer_password@127.0.0.1:5432/svacer_database
* После запуска сервера его веб-интерфейс будет доступен по адресу http://localhost:8080, логин / пароль — admin / admin
 
== Обновление ==
{{Note|type=reminder|text='''Перед обновлением настоятельно рекомендуется [[Help:Backup#Создание и восстановление резервной копии|делать резервные копии]]'''}}
 
Миграции схем БД PostgreSQL и object store происходят автоматически при обновлении на новую версию Svacer. Поэтому для обновления Svacer достаточно остановить сервер старой версии, запустить сервер новой версии, указав ему те же параметры БД и object store, и подождать, пока не пройдет обновление, после чего Svacer запустится как обычно. При больших объемах данных в БД это может занять существенное время, до нескольких часов. Прогресс можно отслеживать по логам сервера.  


Версии не имеют обратной совместимости, то есть после обновления на следующую версию, откатиться на предыдущую можно будет, только восстановив БД из бэкапа.


Используйте для запуска docker-compose файл, находящийся в дистрибутиве Svacer: '''./extra/docker-compose.yml'''. Перейдите в директорию, где находится этот файл и выполните команду
{{Note|type=warn|text=После запуска Svacer при обновлении обязательно дождитесь пока миграция БД завершится. Если прервать процесс во время миграции, принудительно остановив Svacer, база данных может оказаться в неконсистентном состоянии и придется восстанавливать данные из бэкапа.}}


    docker-compose up -d
=== Upgrade notes ===
==== 9-0-0 ====
{{Note|type=reminder|text=При обновлении на эту версию рекомендуем не меньше 8GB RAM для корректности миграций}}


При этом будет запущено два контейнера: PostgreSQL и Svacer. После запуска контейнеров веб-интерфейс Svacer будет доступен по адресу http://localhost:8080
Базово, никаких обязательных ручных действий с базой данных или object store при обновлении на 9-0-0 не требуется. Описанные ниже шаги могут помочь увеличить производительность сервера Svacer или решить возможные проблемы.


'''1.'''


В процессе запуска в текущей директории будут созданы две директории
В версии 9-0-0 поменялся формат object store, поэтому при обновлении с предыдущих версий Svacer на 9-0-0 или выше будет запущена конвертация object store в новый формат. Конвертация сначала записывает новые данные, а потом, если все прошло успешно, удаляет старые. Из-за этого для конвертации нужно примерно в два раза больше свободного дискового пространства, чем занимает текущий object store. При больших размерах object store и медленном диске конвертация может занять много времени.


* postgres_data — для хранения БД PostgreSQL
Конвертация запустится автоматически при обновлении на 9-0-0, но можно запустить вручную отдельно:
* svacer_data — для object store сервера Svacer


svacer-server kvconvert --from <path> --to <path>


Эти директории будут примонтированы в соответствующие контейнеры как volumes, это необходимо для сохранения данных БД и сервера после остановки или перезапуска контейнеров.
Расположение object store в файловой системе описано в [[Help:Backup#Бэкап object store вручную|разделе про бэкапы]].


'''2.'''


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


delete from checkers where id not in (select max(id) from checkers group by (config_id, checker_id, languages, tools));


Остановить сервер Svacer можно, выполнив следующую команду
Если вы уже выполняли этот запрос при [[Help:installation#8-0-0|обновлении на 8-0-0]], то второй раз запускать не обязательно.


    docker-compose down
'''3.'''


Также можно запустить в докер-контейнере только PostgreSQL для последующего запуска Svacer вручную. Используйте файл '''./extra/docker-compose-postgres.yml'''
После обновления на версию 9-0-0 и завершения всех миграций БД (когда станет доступен веб-интерфейс) рекомендуем выполнить команду <code>VACUUM FULL</code> в PostgreSQL для очистки и оптимизации базы данных.


    docker-compose -f docker-compose-postgres.yml up -d
psql -h <postgres_host> -U <username> <svacer_database_name> -c 'VACUUM FULL;'


Чтобы остановить, соответственно
Например:


    docker-compose -f docker-compose-postgres.yml down
psql -h localhost -U svacer svacer_db -c 'VACUUM FULL;'


==== 8-0-0 ====
Если при обновлении на версию 8-0-0 и выше возникает подобная ошибка
Key (config_id, checker_id, languages, tools)=(4cd178ce-a2b2-4692-a45a-f84b145c807b, FB.ICAST_QUESTIONABLE_UNSIGNED_RIGHT_SHIFT, {JAVA}, {SpotBugs}) is duplicated
Это значит, что в БД есть дубликаты чекеров. Выполните следующий SQL-запрос в PostgreSQL-базе Svacer, чтобы удалить их:
delete from checkers where id not in (select max(id) from checkers group by (config_id, checker_id, languages, tools));


=== Установка и запуск вручную ===
== Расширенная конфигурация ==
Для установки Svacer скачайте и распакуйте архив дистрибутива (файл с названием вида '''svacer_release-<version>.zip''').
=== Настройка TLS ===
Svacer может быть сконфигурирован для поддержки TLS несколькими способами. Первый способ — использовать reverse proxy с поддержкой HTTPS и проксированием в Svacer по HTTP, второй — запуск Svacer с нативной поддержкой TLS.


==== Reverse proxy ====
Данный способ позволяет обеспечить безопасную передачу данных только по протоколу HTTPS, данные по протоколу gRPC передаются в незащищенном виде.


При использовании PostgreSQL, предварительно настроенного на каком-либо хосте, необходимо использовать соответствующие параметры запуска. Допустим, PostgreSQL работает на локальном хосте, в нем создана БД '''svacer_db''', доступная от пользователя '''svacer_user''' с паролем '''svacer123'''. В этом случае запустите Svacer со следующими параметрами
===== Nginx =====
Создайте конфигурационный файл с подобным содержанием в '''/etc/nginx/sites-enabled/'''  
<pre>
server {
    listen 443 ssl;
    listen [::]:443 ssl;


     ./bin/svacer server --pg postgres://svacer_user:svacer123@127.0.0.1:5432/svacer_db
     server_name svacer.ispras.ru;


Если вы запустили PostgreSQL в докер-контейнере, используя файл '''./extra/docker-compose-postgres.yml''', то при запуске Svacer параметр '''--pg''' для подключения к БД можно не указывать, поскольку был создан пользователь и база, прописанные в Svacer как параметры по умолчанию.
    # for large data transfers and continuous connections
    client_max_body_size        0;
    proxy_connect_timeout      600;
    proxy_send_timeout          600;
    proxy_read_timeout          600;
    send_timeout                600;


    # path to ssl-certificate and key
    ssl_certificate /etc/ssl/certs/svacer.ispras.ru.crt;
    ssl_certificate_key /etc/ssl/private/svacer.ispras.ru.key;


После запуска сервера его веб-интерфейс будет доступен по адресу http://localhost:8080
    location / {
По умолчанию web сервер запускается на интерфейсе '''0.0.0.0:<port>'''. Для указания отличного  сетевого интерфейса пользователь может использовать опцию '''--listen <network interface>'''.
        include proxy_params;
По умолчанию grpc сервер запускается на интерфейсе '''0.0.0.0:<port>'''. Для указания отличного сетевого интерфейса пользователь может использовать опцию '''--listen-grpc <network interface>'''.


        # to make WebSockets work
        proxy_http_version  1.1;
        proxy_set_header    Upgrade $http_upgrade;
        proxy_set_header    Connection "upgrade";


=== Hooks ===
        # svacer HTTP URL
Для получения данных Hooks при запуске сервера нужно указать опцию '''--hooks <path to JSON file>'''. Эта опция задаёт файл, содержащий информацию о расширении сервера посредством хуков, которые пользователь может вызывать из web-интерфейса.
         proxy_pass http://127.0.0.1:8080;
Каждый хук соответствует некоторому процессу или скрипту, который сервер запускает в ответ на вызов соответствующей команды из web-интерфейса.
Формат файла Hooks следующий:
    {
      "hooks": [
         {
          "id": "<id>",
          "label": "<label >",
          "target": "<target>",
          "input": ["<param1>", "<param2>",…],
          "cmd": "<path to executable>",
          "args": ["<arg1>", “<arg2>”, …]
        },
        ...
      ]
     }
     }
}
</pre>
В этом конфигурационном файле укажите нужное имя сервера, пути к сертификату (можно использовать fullchain-сертификат) и ключу, а также адрес сервера Svacer, куда проксировать. После этого перезапустите Nginx.
  systemctl restart nginx
Если ваш сервер виден из интернета и его внешний IP-адрес привязан к доменному имени, можете использовать Let's Encrypt и Certbot для получения валидного SSL-сертификата. См. [https://www.nginx.com/blog/using-free-ssltls-certificates-from-lets-encrypt-with-nginx/ эту инструкцию].
===== Apache =====
Включите нужные модули в Apache
  sudo a2enmod ssl proxy proxy_http rewrite
Создайте конфигурационный файл с подобным содержанием в '''/etc/apache2/sites-enabled/'''
<pre>
<VirtualHost *:443>
    SSLEngine On
    ProxyPreserveHost On
    ProxyTimeout 600
   
    # path to ssl-certificate and key
    SSLCertificateFile /etc/ssl/certs/svacer.ispras.ru.crt
    SSLCertificateKeyFile /etc/ssl/private/svacer.ispras.ru.key
   
    # svacer HTTP URL
    ProxyPass / http://127.0.0.1:8080/
    ProxyPassReverse / http://127.0.0.1:8080/
    # to make WebSockets work
    ProxyPass /api/ws/ ws://127.0.0.1:8080/api/ws/
    ProxyPassReverse /api/ws/ ws://127.0.0.1:8080/api/ws/
    RewriteEngine on
    RewriteCond %{HTTP:UPGRADE} ^WebSocket$ [NC]
    RewriteCond %{HTTP:CONNECTION} ^Upgrade$ [NC]
    RewriteRule /api/ws/(.*) ws://127.0.0.1:8080%{REQUEST_URI} [P]
    ServerName svacer.ispras.ru
    ServerAdmin svacer@ispras.ru
</VirtualHost>
</pre>
В этом конфигурационном файле укажите нужное имя сервера, пути к сертификату (можно использовать fullchain-сертификат) и ключу, а также адрес сервера Svacer, куда проксировать. После этого перезапустите Apache.
  systemctl restart apache2
==== Нативно ====
Этот способ позволяет обеспечить безопасную передачу данных как по протоколу HTTPS, так и по протоколу gRPC. Если сервер запускается с поддержкой TLS, то эта опция относится как к протоколу HTTPS, так и к протоколу gRPC.
По умолчанию сервер запускается без поддержки TLS, при этом в логах отображается информация об этом.
TLS for REST and gRPC DISABLED
Для запуска сервера с поддержкой TLS необходимо указать сертификат сервера и соответствующий закрытый ключ.
svacer-server run --ssl-cert svacer.crt --ssl-key svacer.key
При этом ключ должен быть в незашифрованном виде. Права доступа к файлу должны быть 0600. В файле сертификата можно указывать цепочку сертификатов. В этом случае сервер, при подключении клиента, будет возвращать всю цепочку. Первым сертификатом в цепочке всегда должен идти сертификат сервера Svacer. Формат файла — PEM. TLS соединение активируется и для протокола REST и для протокола gRPC.
Работа сервера по проктолу TLS сопровождается следующей записью в логе:
Using TLS for REST and gRPC protocols
Работа с таким сервером через CLI происходит как обычно. Для указания необходимости подключаться по TLS можно явно указать протокол в параметре '''--host''', либо добавить опцию '''--ssl'''.
<pre>
svacer upload --host https://example.com
svacer upload --ssl --host example.com
</pre>
Также в клиенте можно определить параметр '''--ssl-ca-certs'''. Он позволяет задать доверенные сертификаты корневых центров. Указывается шаблон файлов (с *) или конкретный файл. Путь к директории должен быть абсолютным. В случае отсутствия этого параметра используется TLS, но сертификат сервера не проверяется. Этому случаю соответствует запись в логе клиента:
Using weak TLS configuration, because no CA certificate found
Если сертификаты были загружены, в логе будет строчка:
added 1 ca certs from /home/user/svacer/svacer.crt
Для администрирования сервера в плане используемого сертификата (например, замена при истечении срока действия) добавлена область в CLI svacer admin: '''server:config'''. В данной области есть 3 команды: '''show''', '''reload''', '''update'''. ID в этом случае нужно всегда указывать в значение '''ssl.cert'''.
* '''show''' — отображает текущий используемый сертификат
:<pre>svacer admin --ssl --host example.com --user admin --password admin --scope server:config --id ssl.cert --action show</pre>
* '''reload''' — заставляет сервер перечитать использованные при старте сервера файлы с сертификатом и ключом
:<pre>svacer admin --ssl --host example.com --user admin --password admin --scope server:config --id ssl.cert --action reload</pre>
* '''update''' — позволяет переслать на сервер новый сертификат (и ключ, если надо) и записать их в указанные при старте сервера файлы. При использовании этой команды нужно сформировать файл с новым сертификатом и, при необходимости, ключом, в формате PEM (используете '''cat''' для объединения сертификата и ключа в один файл) и указать этот файл в параметре value. Если в файле не будет указан закрытый ключ, то сервером будет использован текущий (тот, что был указан при запуске). Данная команда также изменит файлы сертификата и ключа (если он указан), указанные при старте сервера, на новые значения.
:<pre>svacer admin --ssl --host example.com --user admin --password admin --scope server:config --id ssl.cert --action update --value svacer.pem</pre>
:Некоторое время после обновления сертификата сервер может использовать старые сертификаты (для уже установленных соединений). Для новых соединений будет использован обновленный сертификат.
=== Выбор сетевых интерфейсов и портов сервера ===
* По умолчанию web-сервер запускается на всех сетевых интерфейсах, на порту 8080 ('''0.0.0.0:8080'''). Для указания конкретного сетевого интерфейса можно использовать опцию '''--listen <network interface>''', для указания другого порта: '''--port <port_number>.
* Аналогично для grpc-сервера: по умолчанию — '''0.0.0.0:3002''', для выбора конкретного интерфейса: '''--listen-grpc <network_interface>''', для указания другого порта: '''--grpc <port_number>'''.
Пример:
  svacer-server run --listen 127.0.0.1 --port 9090 --listen-grpc 127.0.0.1 --grpc 3004
=== Увеличение лимита открытых файлов ===
Актуально только для Linux.
Если проекты большие, или их много, в object store создается большое количество файлов. Для нормальной работы сервера Svacer при этом рекомендуется увеличивать системный лимит количества одновременно открытых файлов.
В POSIX таких лимита два:
* soft nofiles — текущее максимальное значение
* hard nofiles — общесистемное максимальное значение
В большинстве систем hard значение достаточно большое, а soft обычно маленькое, что и приводит к проблемам. Пример на Debian 11:
  $ ulimit -Sn
  1024
  $ ulimit -Hn
  1048576
Начиная с версии 6-0-0 Svacer пытается автоматически увеличить soft limit до значения hard limit при запуске, а начиная с версии 8-0-0 — проверяет, что увеличить удалось и выводит сообщение с текущим лимитом. Если видите в логах подобную запись — у soft и hard одно, достаточно большое значение — значит все в порядке.
  Open files limit (soft and hard): 1048576
Для более ранних версий, или если на вашем дистрибутиве Linux это не работает автоматически, можете увеличить лимит вручную одним из следующих способов:
* Перед запуском Svacer выполнить из консоли команду, увеличив лимит для текущей сессии
  ulimit -Sn 16384
* Либо один раз увеличить на уровне системы — в файл '''/etc/security/limits.conf''' добавить
  * soft nofile 16384
* Если запускаете Svacer как сервис systemd, добавьте параметр '''LimitNOFILE''' в секцию '''[Service]''' файла описания сервиса.
:В файле из deb/rpm пакета релиза Svacer этот параметр уже добавлен
  [Service]
  LimitNOFILE=16384
:После чего выполните следующие команды, чтобы прочитать обновленный конфиг и перезапустить с ним Svacer
  sudo systemctl daemon-reload
  sudo systemctl restart svacer.service
=== Дополнительные параметры при запуске в docker-контейнере ===
При запуске в докер-контейнере можно указать дополнительные параметры, к примеру добавить конфиг для LDAP.
Для этого переопределите команду запуска (см. референс в [[Dockerfile]]) сервиса svacer в docker-compose файле и допишите туда нужные параметры:
  command: ["/svacer/bin/svacer-server", "run", "--store", "/data/store", "--pg", "postgres://svace:svace@postgresql:5432/svace", "--ldap", "/svacer/ldap.cfg"]
Сам конфигурационный файл можно примонтировать как volume:
  volumes:
    - ./ldap.cfg:/svacer/ldap.cfg
Можете использовать переменные из секции environment docker-compose файла, тогда в строке запуска их надо экранировать с помощью <code>$$</code> и запускать сервер Svacer как команду bash, чтобы в контейнере подставились значения переменных


  environment:
    - SVACER_PG_URL=postgres://svace:svace@postgresql:5432/svace
    - STORE=/data/store
    - LDAP_CONFIG=/svacer/ldap.cfg
  volumes:
    - ./ldap.cfg:/svacer/ldap.cfg
  command: ["bash", "-c", "/svacer/bin/svacer-server run --store $$STORE --pg $$SVACER_PG_URL --ldap $$LDAP_CONFIG"]


'''Параметры Hooks'''
== Обновление детекторов ==
{| class="wikitable"
После установки новой версии Svace требуется обновить описания детекторов в Svacer. Для этого необходимо выполнить команду:
! style="width:100px;" | Параметр || Описание
|-
| ''id''
| Идентификатор хука.<br>Должен быть уникальным в файле
|-
| ''label''
| Имя команды, которую пользователь видит в web-интерфейсе
|-
| ''target''
| Место в UI, в которое будет добавлена команда.<br>
Сейчас поддерживается только одно значение — default. Оно соответствует вкладке Details на правой панели пользовательского интерфейса
|-
| ''input''
| Параметры, которые можно передать в запускаемый процесс, исходя из контекста вызова команды в web-интерфейсе.<br>
Поддерживаемые значения:
* markerID — UUID идентификатор маркера;
* branchID — UUID идентификатор ветки;
* snapshotID — UUID идентификатор снимка;
* projectID — UUID идентификатор проекта;
* url — URL маркера в web-интерфейсе, на котором была вызвана команда;
* marker — будет заменен на полное имя временного файла, содержащего сериализованное в JSON представление маркера, который включает в себя его трассу и информацию о разметке
|-
| ''cmd''
| Полный путь к процессу, который будет запущен. Не должен включать аргументы запуска
|-
| ''args''
| Аргументы, передаваемые в запускаемый процесс. Полный список аргументов запускаемого процесса состоит из списка <args> и списка значений, соответствующих полю <input>
|}


  svacer checkers --upload </path/to/svace>


[[#Top|В начало]]
{{Note}} Обновление описаний детекторов это серьезная операция, которая должна выполняться после предварительного тестирования. Поэтому перед выполнением команды рекомендуется сделать резервную копию базы данных Svacer.''

Latest revision as of 12:59, 11 November 2024

Установка и запуск

Для использования только клиента Svacer достаточно скачать исполняемый файл svacer (или установить deb/rpm пакет).

Для запуска сервера Svacer установите пакеты, указанные в requirements, после чего установите сервер, создайте БД и запустите его.

Requirements

PostgreSQL

Для работы сервера Svacer установите (или запустите в докере) PostgreSQL версии не ниже 14-й, следуя документации postgres.

На Debian-based системах, обычно, достаточно выполнить команду 

 sudo apt install postgresql

Для RedHat-based ОС также установите пакет postgresql-contrib. Пример для Centos 7: 

  sudo yum install -y https://download.postgresql.org/pub/repos/yum/reporpms/EL-7-x86_64/pgdg-redhat-repo-latest.noarch.rpm
  sudo yum install -y postgresql14-server postgresql14-contrib
  sudo /usr/pgsql-14/bin/postgresql-14-setup initdb
  sudo systemctl enable postgresql-14
  sudo systemctl start postgresql-14

Для версий PostgreSQL ниже 13-й требуется явно разрешить подключение к локальному хосту базы с логином/паролем. Для этого проверьте следующие строчки в конце файла /var/lib/pgsql/<version>/data/pg_hba.conf 

 # IPv4 local connections:
 host    all    all    127.0.0.1/32    ident

 # IPv6 local connections:
 host    all    all    ::1/128         ident

Если в последнем столбце указано значение ident, поменяйте его на md5 и перезапустите PostgreSQL. 

 sudo systemctl restart postgresql-12
Запуск PostgreSQL в docker

Можно запустить PostgreSQL в докер-контейнере. Используйте файл docker-compose-postgres.yml 

 docker-compose -f docker-compose-postgres.yml up -d

Чтобы остановить, соответственно 

 docker-compose -f docker-compose-postgres.yml down

При таком способе запуска создается пользователь и база, указанные в Svacer как параметры по умолчанию, поэтому при запуске сервера Svacer параметр --pg можно не указывать (и не менять в конфиг-файле /etc/default/svacer при установке Svacer из пакетов).

Браузер для PDF-отчетов

При запуске Svacer проверяет доступность браузера для генерации PDF. Если он не установлен или генерация не работает, будет использован нативный генератор: менее продвинутый, но для него не нужен браузер. Можно явно включить использование нативного генератора, передав опцию --pdf-generator=native при запуске сервера Svacer.

Для создания PDF-отчетов с использованием нового HTML-генератора установите браузер Google Chrome на машину, где запускается сервер Svacer.

Рекомендуется устанавливать из официального deb- или rpm-пакета, следуя инструкции с сайта google.

При невозможности установить Google Chrome, например если нет пакета для вашего дистрибутива Linux, можно установить Chromium. Его пакет в репозиториях, в зависимости от вышей ОС, может называться chromium-browser или chromium. 

 sudo apt install chromium-browser
 sudo apt install chromium

На RedHat-based ОС 

 sudo yum install chromium

В некоторых случаях генерация с Chromium может не работать. Например, если Svacer установлен из deb-пакета, а Сhromium из snap (на Ubuntu он устанавливается именно так даже при использовании apt) и сервер Svacer запускается от отдельного системного пользователя, от которого Chromium не может запуститься. В этом случае установите Google Chrome, с ним генерация работает.

Установка и запуск из deb/rpm пакета

При установке из deb- или rpm-пакета Svacer ставится в директорию, прописанную в $PATH, поэтому при запуске полный путь к исполняемым файлам указывать не требуется, они будут доступны по имени.

deb

Добавьте apt-репозиторий и установите Svacer из него. 

 echo 'deb [signed-by=/usr/share/keyrings/ispras.gpg] https://repo.ispras.ru/apt /' | sudo tee /etc/apt/sources.list.d/ispras.list
 curl -fsSL https://repo.ispras.ru/apt/key.asc | sudo gpg --dearmor -o /usr/share/keyrings/ispras.gpg
 sudo apt update
 sudo apt install -y svacer

Если нет доступа к репозиторию, можно скачать deb-пакет и установить следующей командой 

 sudo apt install ./svacer_<version>_amd64.deb

rpm

Добавьте dnf/yum-репозиторий и установите Svacer из него 

 curl -fsSL https://repo.ispras.ru/rpm/ispras.repo | sudo tee /etc/yum.repos.d/ispras.repo
 sudo dnf install svacer

Если нет доступа к репозиторию, можно скачать rpm-пакет и установить следующей командой 

sudo dnf install ./svacer-<version>.x86_64.rpm

Создание БД и запуск сервера Svacer

Для создания БД PostgreSQL запустите psql от учетной записи пользователя postgres и выполните соответствующие запросы: 

 sudo su -l postgres
 psql
 postgres=# create database svace;
 postgres=# create user svace with encrypted password 'svace';
 postgres=# grant all privileges on database svace to svace;
 postgres=# alter user svace superuser;

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

При использовании других имен пользователя, БД или пароля нужно поменять параметры подключения к БД в файле /etc/default/svacer 

 SVACER_ARGS="--pg postgres://<user>:<password>@127.0.0.1:5432/<database>"

В этой же строке можно указать прочие аргументы для запуска сервера Svacer.

На Astra Linux необходимо в файле /etc/parsec/mswitch.conf установить параметр zero_if_notfound: yes, иначе при запуске Svacer будет ошибка подключения к БД вида 

 error obtaining MAC configuration for user "svace" (SQLSTATE 57P03)

После создания БД и конфигурации сервера Svacer запустить его можно следующими командами 

 sudo systemctl enable svacer
 sudo systemctl start svacer

После чего проверить успешность запуска командой 

 systemctl status svacer

В случае успешного запуска сервер будет доступен по адресу http://localhost:8080, логин / пароль — admin / admin.

Запуск в docker

Установите docker и docker-compose. Образы PostgreSQL и Svacer размещены на докерхабе, поэтому для их скачивания при запуске нужен интернет.

Используйте для запуска файл docker-compose.yml. Перейдите в директорию, где находится этот файл, и выполните команду 

docker-compose up -d

Запустятся два контейнера: PostgreSQL и Svacer. Веб-интерфейс Svacer будет доступен по адресу http://localhost:8080, логин / пароль — admin / admin

В процессе запуска будут созданы два docker volume для сохранения данных после остановки или перезапуска контейнеров.

  • svacer-postgres — для БД PostgreSQL
  • svacer-object-store — для object store сервера Svacer

Чтобы остановить сервер Svacer выполните следующую команду 

docker-compose down

Для сборки своего докер-образа Svacer можете использовать Dockerfile в качестве референса.

Установка и запуск вручную

Запустите svacer-server из консоли с указанием параметров подключения к БД:

  • Если при создании пользователя и БД PostgreSQL вы использовали для них имя по умолчанию 'svace', как в примере выше, то указывать данные для подключения к БД при запуске сервера не обязательно
 ./svacer-server run
  • Если создавали пользователя или БД с другими именами, то при запуске сервера надо указать их явно
 ./svacer-server run --pg postgres://svacer_user:svacer_password@127.0.0.1:5432/svacer_database

После запуска сервера его веб-интерфейс будет доступен по адресу http://localhost:8080, логин / пароль — admin / admin

Установка и запуск на Windows

Далее будут описаны шаги установки и запуска сервера Svacer. Для использования только клиента Svacer установка и настройка PostgreSQL не требуется.

  • Скачайте установщик PostgreSQL для Windows: https://www.postgresql.org/download/windows
  • Установите PostgreSQL, выбрав, как минимум, компоненты "PostgreSQL Server" и "Command Line Tools"
  • Задайте и запомните пароль на шаге выбора пароля для суперпользователя
  • Остальные параметры при установке можно оставить по умолчанию
  • После установки PostgreSQL откройте консоль, перейдите в директорию, куда установили PostgreSQL, запустите его клиент с указанием пользователя "postgres" и авторизуйтесь с паролем, заданным во время установки
 cd c:\Program Files\PostgreSQL\15\bin
 psql -U postgres
  • Запустится консоль управления PostgreSQL. Выполните в ней следующие команды, чтобы создать БД и пользователя для Svacer
 create database svace;
 create user svace with encrypted password 'svace';
 grant all privileges on database svace to svace;
 alter user svace superuser;
  • Выйдите из консоли PostgreSQL
  • Запустите svacer-server.exe из консоли с указанием параметров подключения к БД. Если при создании пользователя и БД PostgreSQL вы использовали для них имя по умолчанию 'svace', как в примере выше, то указывать данные для подключения к БД при запуске сервера не обязательно
 svacer-server.exe run
  • Если создавали пользователя или БД с другими именами, то при запуске сервера надо указать их явно
 svacer-server.exe run --pg postgres://svacer_user:svacer_password@127.0.0.1:5432/svacer_database
  • После запуска сервера его веб-интерфейс будет доступен по адресу http://localhost:8080, логин / пароль — admin / admin

Обновление

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

Миграции схем БД PostgreSQL и object store происходят автоматически при обновлении на новую версию Svacer. Поэтому для обновления Svacer достаточно остановить сервер старой версии, запустить сервер новой версии, указав ему те же параметры БД и object store, и подождать, пока не пройдет обновление, после чего Svacer запустится как обычно. При больших объемах данных в БД это может занять существенное время, до нескольких часов. Прогресс можно отслеживать по логам сервера.

Версии не имеют обратной совместимости, то есть после обновления на следующую версию, откатиться на предыдущую можно будет, только восстановив БД из бэкапа.

После запуска Svacer при обновлении обязательно дождитесь пока миграция БД завершится. Если прервать процесс во время миграции, принудительно остановив Svacer, база данных может оказаться в неконсистентном состоянии и придется восстанавливать данные из бэкапа.

Upgrade notes

9-0-0

При обновлении на эту версию рекомендуем не меньше 8GB RAM для корректности миграций

Базово, никаких обязательных ручных действий с базой данных или object store при обновлении на 9-0-0 не требуется. Описанные ниже шаги могут помочь увеличить производительность сервера Svacer или решить возможные проблемы.

1.

В версии 9-0-0 поменялся формат object store, поэтому при обновлении с предыдущих версий Svacer на 9-0-0 или выше будет запущена конвертация object store в новый формат. Конвертация сначала записывает новые данные, а потом, если все прошло успешно, удаляет старые. Из-за этого для конвертации нужно примерно в два раза больше свободного дискового пространства, чем занимает текущий object store. При больших размерах object store и медленном диске конвертация может занять много времени.

Конвертация запустится автоматически при обновлении на 9-0-0, но можно запустить вручную отдельно: 

svacer-server kvconvert --from <path> --to <path>

Расположение object store в файловой системе описано в разделе про бэкапы.

2.

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

delete from checkers where id not in (select max(id) from checkers group by (config_id, checker_id, languages, tools));

Если вы уже выполняли этот запрос при обновлении на 8-0-0, то второй раз запускать не обязательно.

3.

После обновления на версию 9-0-0 и завершения всех миграций БД (когда станет доступен веб-интерфейс) рекомендуем выполнить команду VACUUM FULL в PostgreSQL для очистки и оптимизации базы данных. 

psql -h <postgres_host> -U <username> <svacer_database_name> -c 'VACUUM FULL;'

Например: 

psql -h localhost -U svacer svacer_db -c 'VACUUM FULL;'

8-0-0

Если при обновлении на версию 8-0-0 и выше возникает подобная ошибка 

Key (config_id, checker_id, languages, tools)=(4cd178ce-a2b2-4692-a45a-f84b145c807b, FB.ICAST_QUESTIONABLE_UNSIGNED_RIGHT_SHIFT, {JAVA}, {SpotBugs}) is duplicated

Это значит, что в БД есть дубликаты чекеров. Выполните следующий SQL-запрос в PostgreSQL-базе Svacer, чтобы удалить их: 

delete from checkers where id not in (select max(id) from checkers group by (config_id, checker_id, languages, tools));

Расширенная конфигурация

Настройка TLS

Svacer может быть сконфигурирован для поддержки TLS несколькими способами. Первый способ — использовать reverse proxy с поддержкой HTTPS и проксированием в Svacer по HTTP, второй — запуск Svacer с нативной поддержкой TLS.

Reverse proxy

Данный способ позволяет обеспечить безопасную передачу данных только по протоколу HTTPS, данные по протоколу gRPC передаются в незащищенном виде.

Nginx

Создайте конфигурационный файл с подобным содержанием в /etc/nginx/sites-enabled/ 

server {
    listen 443 ssl;
    listen [::]:443 ssl;

    server_name svacer.ispras.ru;

    # for large data transfers and continuous connections
    client_max_body_size        0;
    proxy_connect_timeout       600;
    proxy_send_timeout          600;
    proxy_read_timeout          600;
    send_timeout                600;

    # path to ssl-certificate and key
    ssl_certificate /etc/ssl/certs/svacer.ispras.ru.crt;
    ssl_certificate_key /etc/ssl/private/svacer.ispras.ru.key;

    location / {
        include proxy_params;

        # to make WebSockets work
        proxy_http_version  1.1;
        proxy_set_header    Upgrade $http_upgrade;
        proxy_set_header    Connection "upgrade";

        # svacer HTTP URL
        proxy_pass http://127.0.0.1:8080;
    }
}

В этом конфигурационном файле укажите нужное имя сервера, пути к сертификату (можно использовать fullchain-сертификат) и ключу, а также адрес сервера Svacer, куда проксировать. После этого перезапустите Nginx. 

 systemctl restart nginx

Если ваш сервер виден из интернета и его внешний IP-адрес привязан к доменному имени, можете использовать Let's Encrypt и Certbot для получения валидного SSL-сертификата. См. эту инструкцию.

Apache

Включите нужные модули в Apache 

 sudo a2enmod ssl proxy proxy_http rewrite

Создайте конфигурационный файл с подобным содержанием в /etc/apache2/sites-enabled/ 

<VirtualHost *:443>
    SSLEngine On
    ProxyPreserveHost On
    ProxyTimeout 600
    
    # path to ssl-certificate and key
    SSLCertificateFile /etc/ssl/certs/svacer.ispras.ru.crt
    SSLCertificateKeyFile /etc/ssl/private/svacer.ispras.ru.key
    
    # svacer HTTP URL
    ProxyPass / http://127.0.0.1:8080/
    ProxyPassReverse / http://127.0.0.1:8080/

    # to make WebSockets work
    ProxyPass /api/ws/ ws://127.0.0.1:8080/api/ws/
    ProxyPassReverse /api/ws/ ws://127.0.0.1:8080/api/ws/
    RewriteEngine on
    RewriteCond %{HTTP:UPGRADE} ^WebSocket$ [NC]
    RewriteCond %{HTTP:CONNECTION} ^Upgrade$ [NC]
    RewriteRule /api/ws/(.*) ws://127.0.0.1:8080%{REQUEST_URI} [P]

    ServerName svacer.ispras.ru
    ServerAdmin svacer@ispras.ru
</VirtualHost>

В этом конфигурационном файле укажите нужное имя сервера, пути к сертификату (можно использовать fullchain-сертификат) и ключу, а также адрес сервера Svacer, куда проксировать. После этого перезапустите Apache. 

 systemctl restart apache2

Нативно

Этот способ позволяет обеспечить безопасную передачу данных как по протоколу HTTPS, так и по протоколу gRPC. Если сервер запускается с поддержкой TLS, то эта опция относится как к протоколу HTTPS, так и к протоколу gRPC. По умолчанию сервер запускается без поддержки TLS, при этом в логах отображается информация об этом. 

TLS for REST and gRPC DISABLED

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

svacer-server run --ssl-cert svacer.crt --ssl-key svacer.key

При этом ключ должен быть в незашифрованном виде. Права доступа к файлу должны быть 0600. В файле сертификата можно указывать цепочку сертификатов. В этом случае сервер, при подключении клиента, будет возвращать всю цепочку. Первым сертификатом в цепочке всегда должен идти сертификат сервера Svacer. Формат файла — PEM. TLS соединение активируется и для протокола REST и для протокола gRPC.

Работа сервера по проктолу TLS сопровождается следующей записью в логе: 

Using TLS for REST and gRPC protocols

Работа с таким сервером через CLI происходит как обычно. Для указания необходимости подключаться по TLS можно явно указать протокол в параметре --host, либо добавить опцию --ssl. 

 svacer upload --host https://example.com
 svacer upload --ssl --host example.com

Также в клиенте можно определить параметр --ssl-ca-certs. Он позволяет задать доверенные сертификаты корневых центров. Указывается шаблон файлов (с *) или конкретный файл. Путь к директории должен быть абсолютным. В случае отсутствия этого параметра используется TLS, но сертификат сервера не проверяется. Этому случаю соответствует запись в логе клиента: 

Using weak TLS configuration, because no CA certificate found

Если сертификаты были загружены, в логе будет строчка: 

added 1 ca certs from /home/user/svacer/svacer.crt

Для администрирования сервера в плане используемого сертификата (например, замена при истечении срока действия) добавлена область в CLI svacer admin: server:config. В данной области есть 3 команды: show, reload, update. ID в этом случае нужно всегда указывать в значение ssl.cert.

  • show — отображает текущий используемый сертификат
svacer admin --ssl --host example.com --user admin --password admin --scope server:config --id ssl.cert --action show
  • reload — заставляет сервер перечитать использованные при старте сервера файлы с сертификатом и ключом
svacer admin --ssl --host example.com --user admin --password admin --scope server:config --id ssl.cert --action reload
  • update — позволяет переслать на сервер новый сертификат (и ключ, если надо) и записать их в указанные при старте сервера файлы. При использовании этой команды нужно сформировать файл с новым сертификатом и, при необходимости, ключом, в формате PEM (используете cat для объединения сертификата и ключа в один файл) и указать этот файл в параметре value. Если в файле не будет указан закрытый ключ, то сервером будет использован текущий (тот, что был указан при запуске). Данная команда также изменит файлы сертификата и ключа (если он указан), указанные при старте сервера, на новые значения.
svacer admin --ssl --host example.com --user admin --password admin --scope server:config --id ssl.cert --action update --value svacer.pem
Некоторое время после обновления сертификата сервер может использовать старые сертификаты (для уже установленных соединений). Для новых соединений будет использован обновленный сертификат.

Выбор сетевых интерфейсов и портов сервера

  • По умолчанию web-сервер запускается на всех сетевых интерфейсах, на порту 8080 (0.0.0.0:8080). Для указания конкретного сетевого интерфейса можно использовать опцию --listen <network interface>, для указания другого порта: --port <port_number>.
  • Аналогично для grpc-сервера: по умолчанию — 0.0.0.0:3002, для выбора конкретного интерфейса: --listen-grpc <network_interface>, для указания другого порта: --grpc <port_number>.

Пример: 

 svacer-server run --listen 127.0.0.1 --port 9090 --listen-grpc 127.0.0.1 --grpc 3004

Увеличение лимита открытых файлов

Актуально только для Linux.

Если проекты большие, или их много, в object store создается большое количество файлов. Для нормальной работы сервера Svacer при этом рекомендуется увеличивать системный лимит количества одновременно открытых файлов.

В POSIX таких лимита два:

  • soft nofiles — текущее максимальное значение
  • hard nofiles — общесистемное максимальное значение

В большинстве систем hard значение достаточно большое, а soft обычно маленькое, что и приводит к проблемам. Пример на Debian 11: 

 $ ulimit -Sn
 1024
 $ ulimit -Hn
 1048576

Начиная с версии 6-0-0 Svacer пытается автоматически увеличить soft limit до значения hard limit при запуске, а начиная с версии 8-0-0 — проверяет, что увеличить удалось и выводит сообщение с текущим лимитом. Если видите в логах подобную запись — у soft и hard одно, достаточно большое значение — значит все в порядке. 

 Open files limit (soft and hard): 1048576

Для более ранних версий, или если на вашем дистрибутиве Linux это не работает автоматически, можете увеличить лимит вручную одним из следующих способов:

  • Перед запуском Svacer выполнить из консоли команду, увеличив лимит для текущей сессии
 ulimit -Sn 16384
  • Либо один раз увеличить на уровне системы — в файл /etc/security/limits.conf добавить
 * soft nofile 16384
  • Если запускаете Svacer как сервис systemd, добавьте параметр LimitNOFILE в секцию [Service] файла описания сервиса.
В файле из deb/rpm пакета релиза Svacer этот параметр уже добавлен
 [Service]
 LimitNOFILE=16384
После чего выполните следующие команды, чтобы прочитать обновленный конфиг и перезапустить с ним Svacer
 sudo systemctl daemon-reload
 sudo systemctl restart svacer.service

Дополнительные параметры при запуске в docker-контейнере

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

Для этого переопределите команду запуска (см. референс в Dockerfile) сервиса svacer в docker-compose файле и допишите туда нужные параметры: 

 command: ["/svacer/bin/svacer-server", "run", "--store", "/data/store", "--pg", "postgres://svace:svace@postgresql:5432/svace", "--ldap", "/svacer/ldap.cfg"]

Сам конфигурационный файл можно примонтировать как volume: 

 volumes:
   - ./ldap.cfg:/svacer/ldap.cfg

Можете использовать переменные из секции environment docker-compose файла, тогда в строке запуска их надо экранировать с помощью $$ и запускать сервер Svacer как команду bash, чтобы в контейнере подставились значения переменных 

 environment:
   - SVACER_PG_URL=postgres://svace:svace@postgresql:5432/svace
   - STORE=/data/store
   - LDAP_CONFIG=/svacer/ldap.cfg
 volumes:
   - ./ldap.cfg:/svacer/ldap.cfg
 command: ["bash", "-c", "/svacer/bin/svacer-server run --store $$STORE --pg $$SVACER_PG_URL --ldap $$LDAP_CONFIG"]

Обновление детекторов

После установки новой версии Svace требуется обновить описания детекторов в Svacer. Для этого необходимо выполнить команду: 

 svacer checkers --upload </path/to/svace>

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

Retrieved from "https://svacer.ispras.ru/mediawiki/index.php?title=Help:Installation&oldid=2168"