Перейти к основному содержимому

· 3 мин. чтения
Антон Трофимов

На днях состоялось обновление документации для продукта KOMRAD. Спешим раскрыть все секреты касательно того, как это произошло.

Немного истории

3 года назад мы готовили сертификационную документацию по требованию ФСТЭК и задумались над тем, что сложно поддерживать её в актуальном состоянии. Дело в том что сертификационная документация очень долго обновляется и вообще это сложный процесс для всех:

  • для заказчика (он постоянно должен у спашивать саппорта "а может ли продукт то, что не описано в руководстве, и как это сделать?"
  • для разработчика (согласовать новую версию руководства с ФСТЭК, а у нас оно лежит на диске, пересчитать КС и отправить всем)
  • для ФСТЭКа ничего кроме руководства не меняется, но документация все равно проходит все формальные процессы в ведомстве, и это может быть очень долго
  • для саппорта (у саппорта должна быть либо своя база знаний, либо мини-инструкции на любой случай)

Antora

Поэтому мы задумались о том, чтобы иметь электронную документацию, которая потенциально решила бы все наши проблемы. В первый раз мы не выбирали долго, форкнули готовый проект на Antora и переделали её под себя настроили CI/CD, начали документировать. Антора немного специфична, например, формат разметки текста в ней asciidoc. Поскольку это была наша первая электронная документация, мы хотели быстро её сделать и быстро выложить. С первым мы справились действительно быстро, сделали простое деление на руководство администратора и оператора, остальные статьи были отсылками к другим документам, но, в итоге, мы посчитали, что более структурировано будет выглядеть архитектура с продуктовой логикой, вдохновлялись документацией.

Стоит отметить, что у таких проектов, как Антора есть своя философия, там есть своя структура папок, есть рекомендации по CI, но мы, в большей степени, её игнорировали с самого начала. И не стоит забывать, что мы переделывали форк под себя, мы пытались оградить UI и бэкенд специалистов от работы, связанной с документацией, но повышать зависимости надо и документация начала ломаться. Большой проблемой стал поиск, когда локальный поиск сломался, мы попробовали его переписать, но безуспешно, UI жаловался на легаси код и отклонял наши хотелки, например, возможность зумить изображения. Вершиной всего стало то, что из-за неверной настройки нам пришлось бы потратить много времени на добавление новых версий, хотя, в репозитории документации уже были готовые ветки, из которых просто нужно было собрать версии.

Муки выбора

Есть достаточное количество проектов для электронной документации. В большей степени, они используют Markdown, очевидно, он проще и популярнее, поэтому для нас это было не ограничением, но препятствием. Мы рассматривали такие проекты:

По набору функций нас впечатлили Docusaurus и Gitbook, но у Docusaurus больше запас на развитие документации, поэтому мы сделали выбор в его пользу. Развитие - это фичи, которые можно опционально подключить, в docusaurus - это плагины, сейчас их не так много, по причине обновления docusaurus до версии 3, на 2-й версии их было огромное количество, но не все ещё добавили поддержку 3-й версии.

Docusaurus

Новые фичи:

  • локальный поиск
  • зум изображений
  • работа с формами
  • тёмная тема
  • версионирование
  • новое индексирование

Мы перенесли все документы в их исходном виде и добавили ещё одну версию 4.5.Х, сейчас она в стадии Beta и выдаётся по запросу, но уже сейчас есть доступ к её актуальной документации. Новые функции и новая логика элементов и страниц будет правиться только для версии 4.5.

· 2 мин. чтения
Антон Трофимов

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

Часто поступают запросы, связанные с падением сервисов или коллекторов через несколько месяцев после установки. В большинстве случаев это связано с сертификатами. Давайте разберёмся в чём дело.

Какие у нас есть сертификаты?

Мы составляем цепочку сертификатов, чтобы в случае компрометации одного из цепочки не была скомпрометирована вся система. В общем случае, подразумевается наличие сертификатов:

  • Корневой (CA)
  • Серверный (Server)
  • Клиентский(Client)
  • Браузерный(Browser)

Где лежат сертификаты?

Сертификаты, расположенные в /var/lib/echelon/komrad/certs/, являются одним из гарантов безопасности Вашей системы. На папку есть специальные разрешения, доступ к ней должен быть у группы root и пользователя komrad.

Какой срок годности у сертификатов?

При установке в автоматическом режиме установщик сам выставит сроки их годности.

  • Корневой (CA) 12 месяцев
  • Серверный (Server) 3 месяца
  • Клиентский(Client) 3 месяца
  • Браузерный(Browser) 3 месяца

Как определить что проблема с сертификатом?

В лога Вы увидите ошибку:

x509 expired certificate

Как проверить срок годности сертификатов?

Выполните команду:

openssl x509 -in /var/lib/echelon/komrad/certs/ca.pem -text -noout | grep "Not After" && openssl x509 -in /var/lib/echelon/komrad/certs/server.pem -text -noout | grep "Not After" && openssl x509 -in /var/lib/echelon/komrad/certs/client.pem -text -noout | grep "Not After"

После выполнения команды будет выведен результат. Если напротив сертификата будет стоять параметр Not Afterраньше текущей даты значит сертификат сертификат просрочен, необходимо выпустить сертификаты. Выпустить серверный сертификат

sudo komrad-cli certificates create server --organization “Echelon” localhost 127.0.0.1 $(hostname -I) $(hostname) --ca /var/lib/echelon/komrad/certs/ca.pem --ca-key /var/lib/echelon/komrad/certs/ca-key.pem

Выпуск клиентского сертификата

sudo komrad-cli certificates create client --ca /var/lib/echelon/komrad/certs/ca.pem --ca-key /var/lib/echelon/komrad/certs/ca-key.pem

Браузерный сертификат

sudo cp ./client-browser.p12 client.pem client-key.pem server-key.pem server.pem /var/lib/echelon/komrad/certs

Не забудьте указать необходимые сроки годности флагом expire например так:

sudo komrad-cli certificates create ca --expire 24m

Если сертификаты по какой-то причине не воспринимаются сервисом, например они лежат в не стандартной папке, дайте разрешение на их использование пользователю komrad выполнив команды :

sudo chown -R komrad:komrad /var/lib/echelon/komrad/certs
sudo chmod -R 755 /var/lib/echelon/komrad/certs
sudo chmod 0640 /var/lib/echelon/komrad/certs/server-key.pem
sudo chown root:komrad /var/lib/echelon/komrad/certs/server-key.pem
sudo usermod -a -G komrad postgres
sudo chmod 755 client-browser.p12

Не забудьте перезапустить сервисы!