Руководство по системному администрированию#

Сценарии администрирования#

Все сценарии, описанные в данном разделе, выполняются пользователем с правами администратора.

Настройка CodeScanner#

Параметры конфигурации устанавливаются в конфигурации проекта и применяются при запуске сканирования. Проект содержит конфигурационный файл sonar-project.properties, который содержит пары ключ-значение, используемые для установки значений конфигурации. Поскольку некоторая конфигурация (например, номер сборки) может различаться для каждого задания CI, эти параметры также можно установить в файле конфигурации CI.

sonar.host.url=https://sonar.appirio.com
sonar.projectKey=group-project
sonar.projectName=group/project
sonar.projectDescription=Core code for Groups project
sonar.sources=.
sonar.exclusions=**/__tests__/*,**/__mocks__/*,sonar-project.properties,coverage/**/*
sonar.javascript.lcov.reportPaths=coverage/lcov.info
sonar.sourceEncoding=UTF-8

• sonar.projectKey — уникальный идентификатор проекта. Если этот ключ изменить, то будет создан новый проект CodeScanner.

• sonar.sources — параметр, указывающий, какие каталоги сканировать. "." означает, что сканированию подлежат все измененные файлы в текущем каталоге.

Настройка глобальных разрешений#

Чтобы установить глобальные разрешения, войдите в систему как системный администратор и перейдите в раздел «Администрирование» > «Безопасность» > «Глобальные разрешения», в котором будут доступны следующие подразделы:

• Администрирование системы включает все функции администрирования экземпляра, общие настройки;

• Администрирование профилей качества включает все действия с профилями качества;

• Администрирование Quality Gate (порогов качества) включает все действия с Quality Gate;

• Выполнение анализа включает настройки выполнения анализа, включая защищенные параметры, такие как пароли;

• Создание проектов инициализирует структуру нового проекта перед его первым анализом. Это разрешение также требуется при проведении первого анализа проекта, который еще не был создан с помощью графического интерфейса.

Примечание:
Пользователям с любым явным разрешением на создание в пользовательском интерфейсе в верхнем меню доступен пункт с пиктограммой «+», предоставляющий доступ к этим функциям. Если эти разрешения будут удалены у глобальных администраторов, они потеряют быстрый доступ к ним через верхнее меню, но сохранят доступ к созданию через меню «Администрирование». Создание элемента не предоставляет автоматически права на его администрирование.

Настройка разрешений проекта#

Разрешения проекта доступны в меню администрирования на уровне проекта: «Администрирование» > «Разрешения».

Видимость проекта может переключаться между общедоступной и частной. Если сделать проект частным, его исходный код и показатели будут скрыты от группы Anyone.

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

В CodeScanner доступны следующие разрешения на уровне проекта:

• Администрирование замечаний — включает возможность доступа к изменению типа и серьезности замечания, пометки замечаний как «Не исправим» или «Ложное срабатывание» (пользователям также требуется разрешение «Обзор»).

• Администрирование проекта — включает возможность доступа к настройкам проекта и выполнению задач администрирования (пользователям также необходимо разрешение «Обзор», если проект приватный).

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

Частные сканирования имеют два дополнительных разрешения:

• Просмотр — включает возможность общего доступа к просканированному проекту;

• Просмотр исходного кода — включает возможность просмотра исходного кода просканированного проекта.

Обратите внимание, что разрешения не суммируются. Например, если требуется возможность администрирования проекта, то для возможности доступа к проекту также необходимо предоставить разрешение на просмотр проекта (которое по умолчанию предоставляется для общедоступного проекта).

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

Настройка шаблонов разрешений (разрешений по умолчанию)#

CodeScanner поставляется с шаблоном разрешений по умолчанию, предоставляющим определенные разрешения определенным группам при создании проекта (сканирования). Этот шаблон можно редактировать. Можно также создавать дополнительные шаблоны. Для отдельных типов ресурсов можно создать отдельные проекты.

Для работы с шаблонами разрешений перейдите в раздел «Администрирование» > «Безопасность» > «Шаблоны разрешений».

Для создания нового шаблона нажмите кнопку «Создать».

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

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

Настройка системного журнала и метрик мониторинга#

Управление пользовательскими системами показателей#

Система показателей - набор правил, с помощью которых CodeScanner проверяет код в программном модуле на его читаемость, уязвимость, дублирование и т.д. Каждая система показателей имеет свое значение, хранящее в себе оценку сканирования определенного проекта. Тип значения можно задавать вручную.

Чтобы создать систему показателей, для которой требуется сохранить значение, перейдите в раздел «Administration» > «Configuration» > «Custom Metrics»:

Управление пользовательскими оценками#

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

Значения пользовательских оценок можно вводить на уровне проекта и на уровне модуля. Чтобы добавить значение пользовательской оценки, войдите в систему как администратор проекта, выберите нужный проект и перейдите в «Сканирования» > Любое сканирование > «Measures». Ниже представлена открывшаяся таблица, содержащая последнее значение, введенное для каждой системы показателей:

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

На этой странице можно отредактировать или удалить существующее значение или ввести новое, как показано ниже:

Новое значение для пользовательской оценки будет выбрано при следующем анализе компонента и показано на странице «Values».

Настройка принудительной аутентификации#

По умолчанию CodeScanner принудительно выполняет аутентификацию пользователя. Можно отключить принудительную аутентификацию пользователей и разрешить анонимным пользователям просматривать проекты и выполнять анализы в экземпляре. Для этого войдите в сервис как системный администратор, перейдите в раздел «Администрирование» > «Конфигурация» > «Общие параметры» > «Безопасность» и отключите свойство «Принудительная проверка подлинности пользователя».

Примечание:
Отключение принудительной аутентификации пользователя может подвергнуть CodeScanner угрозам безопасности. Настоятельно рекомендуется принудительно выполнять аутентификацию пользователей в CodeScanner или тщательно настраивать безопасность (разрешения пользователей, видимость проекта и т. д.) в инструменте.

Очистка данных#

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

Для хранения состояния исходного кода на момент сканирования создаются мгновенные снимки состояния ("snapshots"). Снимки состояния также удаляются по истечении определенного срока.

Ниже приведена конфигурация правил по умолчанию:

1. Для каждого проекта действуют следующие правила:

• по истечении суток сохраняется только один снимок;

• по истечении одного месяца сохраняется только один снимок за каждую неделю;

• по истечении одного года сохраняется только один снимок за каждый месяц;

Примечание

Снимки, отмеченные событием (например, изменение версии при анализе), не удаляются для вышеперечисленных правил по истечении заявленного времени. Все снимки, ключая снимки, отмеченные событием, удаляются по истечении пяти лет.

• по истечении двух лет сохраняются только снимки с событиями, которые связаны с версий;

• снимки без событий или с другими типами событий удаляются.

2. Все закрытые (решенные/удаленные) замечания старше 30 дней удаляются.

3. История на уровне пакета/каталога удаляется.

Данные настройки можно изменить в разделе «Администрирование» > «Общие» > «Очистка базы данных».

Визуальные настройки#

Иконка CodeScanner#

Чтобы установить иконку для CodeScanner, перейдите в раздел «Администрирование» > «Основные» > «Внешний вид». и укажите URL-адрес и ширину изображения. Ширина будет автоматически изменена таким образом, чтобы высота иконки составила 30 пикселей. Иконка будет использоваться как в строке меню, так и на странице «О программе».

Содержание страницы «О программе»#

Чтобы добавить контент на страницу «О программе», на которую по умолчанию попадают анонимные пользователи, перейдите в раздел «Администрирование» > «Основные» > «Внешний вид».

Уведомления#

Механизм уведомлений#

По окончании каждого анализа уведомления формируются для каждого подписавшегося пользователя. Затем асинхронно эти уведомления отправляются по электронной почте.

Периодичность обработки очереди уведомлений задается параметром sonar.notifications.delay (в секундах) в файле $CodeScanner_HOME/conf/sonar.properties.

Для применения нового значения следует перезапустить CodeScanner.

Обратите внимание
Иногда могут быть некоторые расхождения между значениями, отображаемыми в электронном письме, и значениями, отображаемыми в веб-интерфейсе. Это происходит, если между отправкой электронного письма и переходом пользователя по ссылке «Замечания» в этом электронном письме был проведен другой анализ.

Получатели уведомлений#

Для получения уведомлений пользователь должен подписаться на уведомления. Администратор не может подписать другого пользователя на получение уведомлений.

Единственным исключением является случай, когда уведомления будут автоматически (без согласия пользователя) отправляться пользователям с правами настройки профилей качества - при обновлении встроенных профилей качества. Эти обновления могут приходить только при обновлении модуля или соответствующего анализатора. Этот тип уведомлений включен по умолчанию и может быть выключен глобально в разделе «Администрирование» > «General».

Конфигурация электронной почты#

Чтобы настроить сервер электронной почты, перейдите в раздел «Администрирование» > «Основные» > «Email».

Также проверьте состояние базового URL-адреса сервера в разделе «Администрирование» > «Основные» > «General», чтобы убедиться, что ссылки из электронных писем с уведомлениями ведут на правильный URL-адрес сервера CodeScanner.

Перезапуск#

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

• в системной консоли выполнить команду sonar.sh restart;

• в пользовательском интерфейсе в разделе «System info» выбрать соответствующую команду.

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

Чтобы отфильтровать проекты, просканированные ранее определенной даты, а затем использовать массовое удаление для удаления отфильтрованных проектов, в разделе «Администрирование» > «Проекты» > «Управление» можно выполнить поиск «Последний анализ до».

Это можно автоматизировать с помощью соответствующего WebAPI:

api/projects/bulk_delete?analyzedBefore=YYYY-MM-DD

События системного журнала#

Журналы#

Ведение журнала на стороне сервера контролируется параметрами, заданными в файле $CodeScanner-HOME/conf/sonar.properties.

Создаются 4 файла журнала: по одному на процесс CodeScanner.

Уровень журналирования#

Уровень журналирования на стороне сервера можно настроить с помощью параметра sonar.log.level. Поддерживаемые значения:

• INFO - по умолчанию;

• DEBUG - для расширенных журналов;

• TRACE - показать расширенные журналы и все запросы SQL. Ведение журнала уровня TRACE замедляет работу серверной среды и должно использоваться только для отслеживания проблем с производительностью веб-запросов.

Уровень журналирования по процессам#

Уровень журналирования на стороне сервера можно более точно настроить для 4-х процессов CodeScanner Server с помощью следующих параметров:

• sonar.log.level.app - для основного процесса CodeScanner (он же WrapperSimpleApp, процесс начальной загрузки, запускающий 3 других);

• sonar.log.level.web - для веб-сервера;

• sonar.log.level.ce - для ComputeEngineServer;

• sonar.log.level.es - для поискового сервера.

Ротация журнала#

Для управления ротацией журнала используйте sonar.log.rollingPolicy со следующими параметрами:

• time:[value]- для ротации по времени. Например, можно использовать time:yyyy-MM-dd для ежедневной ротации и time:yyyy-MM для ежемесячной ротации;

• size:[value] - для ротации по размеру. Например, size:10MB;

• none - при отсутствии ротации. Обычно это используется, когда журналы обрабатываются внешней системой, такой как logrotate.

• sonar.log.maxFiles - максимальное количество сохраняемых файлов. Этот параметр игнорируется, если для sonar.log.rollingPolicy установлено значение "none".

Ротация журнала основного процесса (sonar.log) определяется в файле wrapper.conf. По умолчанию основной процесс будет менять файл sonar.log каждый день, если есть новый контент для регистрации.

Ротация журнала в основном процессе может быть настроена с помощью следующих параметров:

• wrapper.logfile.maxsize=value[m for mb, k for kb]

• wrapper.logfile.maxfiles=value

• wrapper.logfile.rollmode=DATE|SIZE

wrapper.logfile.maxsize и wrapper.logfile.maxfiles учитываются только в том случае, если в wrapper.logfile.rollmode установлено значение SIZE.

Для корректной работы при указании значения "DATE" для параметра wrapper.logfile.rollmode, файл, заданный параметром wrapper.logfile, должен содержать маркер yyyy-MM-dd.

Доступ к журналам из пользовательского интерфейса к журналам#

Страница «Информация о системе» позволяет выгружать текущие файлы журнала (файлы журнала регулярно меняются) и настраивать уровень журналирования с помощью элементов управления в верхней части страницы. Заданные здесь настройки являются временными и действуют только до следующего перезапуска CodeScanner, после чего уровень журналирования будет сброшен до стандартного значения, установленного в $CodeScanner-HOME/conf/sonar.properties. Несмотря на это, можно изменить свой уровень журналирования со значения INFO, но обязательно нужно изменить его обратно, как только это станет возможным. Файлы журнала могут занимать много места на более подробных уровнях журналирования.

События мониторинга#

Для получения общей информации о состоянии CodeScanner используйте WebAPI api/system/health.

Память процесса Java#

Сервер приложений CodeScanner состоит из 2-х основных процессов Java:

• Доступ в интернет (включая встроенный веб-сервер);

• Compute Engine.

Каждый из вышеперечисленных Java-процессов имеет собственные параметры памяти, которые можно настроить в файле sonar.properties. Настройки памяти по умолчанию, поставляемые с CodeScanner, подходят для большинства случаев. Если CodeScanner используется для работы с большим колличеством данных (более 100 пользователей или более 5000000 строк кода) или как сервис, который является частью конвейера непрерывной интеграции, то следует отслеживать использование памяти и ЦП всеми Java-процессами вместе с общим дисковым пространством. Мониторинг позволяет отследить недостаточность ресурсов определенным процессам с целью принятия дальнейших мер для оптимизации.

Настройки памяти#

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

• инструменты мониторинга показывают, что один или несколько процессов CodeScanner достигают предела памяти;

• любой из процессов CodeScanner дает сбой и/или генерирует ошибку нехватки памяти в файле sonar.log;

• сбой фоновой задачи CodeScanner с ошибкой нехватки памяти в журнале фоновой задачи;

Можно увеличить максимальный объем памяти, выделяемой соответствующему процессу, увеличив его параметр памяти -Xmx в файле sonar.properties:

• Для доступа в интернет: sonar.web.javaOpts

• Для Compute Engine: sonar.ce.javaOpts

Для параметра -Xmx доступно указание значения как в мегабайтах (например, -Xmx2048m), так и в гигабайтах (например, -Xmx2G).

MBean-компоненты JMX#

Сервер CodeScanner обеспечивает видимость состояния и процессов, которые происходят внутри системы, с помощью JMX MBeans.
В дополнение к классическим Java MBeans, предоставляющим информацию о системе, процессах, памяти и потоках на сервере CodeScanner появляется доступ к еще трем MBean-компонентам:

• ComputeEngine MBean;

• База данных MBean;

• CodeScanner MBean.

Примечание

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

MBean (ComputeEngineTasks)#

MBean (База данных)#

Одни и те же атрибуты доступны как для ComputeEngineServer, так и для WebServer.

MBean (CodeScanner)#

Активация JMX#

Локальный доступ#

Если инструмент работает на том же сервере, что и сервер CodeScanner, действия для активации JMX для просмотра MBean-компонентов CodeScanner не требуются.

Удаленный доступ#

Ниже представлены примеры конфигурации для активации удаленного доступа к JMX MBeans.

Для веб-сервера:

# JMX WEB - 10443/10444
sonar.web.javaAdditionalOpts=-Dcom.sun.management.jmxremote=true -Dcom.sun.management.jmxremote.ssl=false -Dcom.sun.management.jmxremote.authenticate=true -Dcom.sun.management.jmxremote.port=10443 -Dcom.sun.management.jmxremote.rmi.port=10444 -Dcom.sun.management.jmxremote.password.file=/opt/sonarsource/sonar/conf/jmxremote.password -Dcom.sun.management.jmxremote.access.file=/opt/sonarsource/sonar/conf/jmxremote.access

Для поискового сервера:

sonar.search.javaAdditionalOpts=-Dcom.sun.management.jmxremote=true -Dcom.sun.management.jmxremote.ssl=false -Dcom.sun.management.jmxremote.authenticate=true -Dcom.sun.management.jmxremote.port=19010 -Dcom.sun.management.jmxremote.rmi.port=19011 -Dcom.sun.management.jmxremote.password.file=/opt/sonarsource/sonar/conf/jmxremote.password -Dcom.sun.management.jmxremote.access.file=/opt/sonarsource/sonar/conf/jmxremote.access

Для ComputeEngine:

Отсутствует конкретная запись javaAdditionalOpts. Необходимо изменить запись sonar.ce.javaOpts.

Пример jmxremote.access:

#
# JMX Access Control file
#
reader readonly
admin readwrite \
create javax.management.monitor.*,javax.management.timer.*,com.sun.management.*,com.oracle.jrockit.* \
unregister

Пример jmxremote.password:

#
# JMX Access Password file
#
reader readerpassword
admin adminpassword

Примечание
Для jmxremote.password требуется применить chmod 600 или 400 по соображениям безопасности.

Часто встречающиеся проблемы и пути их устранения#

Типовые проблемы не выявлены. В случаях сбоев диагностику ситуации следует начинать с проверок:

• подключения клиента (компьютера пользователя) к сети;

• доступности сервера CodeScanner - проверка доступности страниц сервиса;

• в случае неудачной аутентификации необходимо обратить внимание на корректность введенного логина/пароля при входе в CodeScanner.