Общие сведения

Раздел содержит инструкции по настройке и использованию продукта «Служба управления конфигурациями "Осмакс"».

Настройка режима мульти-мастер с автоматическим переключением (failover)

Режим мульти-мастер с автоматическим переключением (failover) используется для бесперебойного обслуживания большого количества устройств в инфраструктуре.

При стандартном подключении агент (minion) получает открытый ключ проверки от сервера управления (master) и, в случае сбоя сети или оборудования, выдает ошибку и завершает работу. В режиме мульти-мастер с автоматическим переключением (failover) при неисправности одного сервера управления (master) агент (minion) переключается на следующий и продолжает работу.

Чтобы настроить режим мульти-мастер с автоматическим переключением (failover), необходимо:

  1. Включить настройку подписи открытого ключа на серверах управления (masters).

  2. Включить настройку проверки подписи открытых ключей на агентах (minions).

  3. Включить режим мульти-мастер с автоматическим переключением (failover) на агентах (minion).

Подробную информацию о режиме мульти-мастер с автоматическим переключением (failover) см. в официальной документации.

Настройка подписи открытого ключа на серверах управления (masters)

  1. Cоздайте файл конфигурации сервера управления (master) /etc/salt/master.d/master_sign_pubkey.conf.

  2. В конфигурационном файле сервера управления (master) включите настройку подписи всех открытых ключей, установив значение параметра:

    master_sign_pubkey: True

  3. Перезапустите службу salt-master. После перезапуска сервер управления (master) автоматически создаст новую пару ключей:

    master_sign.pem
master_sign.pub

  4. (Опционально) задайте имя для пары ключей подписи, установив значение параметра:

    master_sign_key_name: <name_without_suffix>

Сервер управления (master) создаст эту пару ключей при перезапуске и будет использовать ее для создания подписи открытых ключей, прикрепленной к ответу аутентификации.

Вычисления выполняются для каждого запроса аутентификации агента (minion). Если большое количество агентов (minions) часто аутентифицируются, рекомендуется использовать настройки conf_master:master_pubkey_signature и conf_master:master_use_pubkey_signature, описанные ниже.

Если используются несколько серверов управления (masters), и они должны подписывать свои ответы аутентификации, пара ключей master_sign.* должна быть скопирована на каждый сервер управления (master). В противном случае агент (minion) не сможет проверить открытые ключи сервера управления (master) при подключении к другому серверу управления (master), так как подпись открытых ключей была создана с другой парой ключей.

Настройка параметров оптимизации производительности работы сервера управления (master)

При описанной выше настройке сервер управления (master) вычисляет подпись для каждого запроса аутентификации, что требует большого количества ресурсов процессора.

Чтобы избежать высокой нагрузки, сервер управления (master) может использовать созданную заранее подпись публичного ключа. Такая подпись сохраняется в виде строки в кодировке Base64, которую сервер управления (master) читает один раз при запуске и прикрепляет только эту строку к ответам аутентификации.

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

Чтобы создать такую подпись, выполните команду:

salt-key --gen-signature

В директории сервера управления (master) pki будет создан файл с подписью по умолчанию:

/etc/salt/pki/master/master_pubkey_signature

Это простой текстовый файл с двоичной подписью, преобразованной в base64. Если пара подписи еще не существует, пара подписи и файл подписи будут автоматически созданы за один вызов:

salt-key --gen-signature --auto-create

Чтобы сервер управления (master) использовал пересозданную подпись, установите значение параметра:

master_use_pubkey_signature: True

Для этого в каталоге сервера управления (master) pki должен присутствовать файл master_pubkey_signature с правильной подписью. Если у файла будет другое имя, задайте его, указав значение параметра:

master_pubkey_signature: <filename>

При наличии большого количества серверов управления (masters) и открытых ключей (по умолчанию и для подписи) рекомендуется использовать имя хоста salt-masters для имен файлов подписи. Подписи легко перепутать, поскольку они не несут никакой информации о ключе, из которого была создана подпись.

Настройка проверки подписи открытых ключей на агентах (minions)

  1. Скопируйте открытый ключ (по умолчанию master_sign.pub) с сервера управления (master) в каталог агента (minion) pki:

    /etc/salt/pki/minion/master_sign.pub
    Для проверки подписи агент (minion) должен иметь доступ только к открытому ключу. Нельзя копировать файл master_sign.pem. Он должен храниться только на сервере управления (master).

  2. Включите проверку подписи открытого ключа на агенте (minions) — в конфигурационном файле агента (minion) задайте значение параметра:

    verify_master_pubkey_sign: True

  3. Перезапустите агента (minion).

При необходимости вы можете запускать проверку для каждой попытки аутентификации, которые могут выполняться довольно часто. Например, только запуск агента (minion) инициирует 6 проверок подписи: для аутентификации, майнинга, highstate и т. д. Для этого включите настройку:

always_verify_signature: True

Включение режима мульти-мастер с автоматическим переключением (failover) на агенте (minion)

  1. Задайте список адресов серверов управления (masters):

    master:
    - 172.16.0.10
    - 172.16.0.11
    - 172.16.0.12

    В случае сбоев агент (minion) будет выполнять подключение к серверам управления (masters) по очереди в указанном порядке.

  2. (Опционально) чтобы подключение выполнялось в случайном порядке, а не в порядке, указанном в параметре master, установите значение параметра:

    random_master: True

  3. Задайте тип сервера управления (masters):

    master_type: failover

    Первый сервер управления (master), принявший агента (minion), будет использоваться агентом (minion).

  1. (Опционально) укажите временной интервал в секундах, через который будет выполняться проверка подключения агента (minion) к серверу управления (master), установив значение параметра:

    master_alive_interval: <seconds>

Если будет установлена потеря связи, агент (minion) временно удалит сервер управления (master) из списка и попробует подключиться к другому серверу управления (master), выбрав следующий в порядке очереди или случайным образом, в зависимости от заданных настроек.

Работа с формулами

Работа с формулами включает этапы:

  1. Написание формулы.

  2. Добавление формулы в S3-совместимое хранилище, на использование которого настроен сервер управления (master).

  3. Создание конфигурации для формулы и импорт в кабинете администратора.

  4. Добавление версии конфигурации.

Принципы написания формулы

Формула — это обычная директория, которая именуется согласно шаблону: <top_level_dir>-formula.

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

  • обязательные:

    • <top_level_dir>/init.sls — главный файл с состояниями формулы; может включать в себя другие файлы с расширением .sls через директиву include;

    • <top_level_dir>/clean.sls — файл отката состояний формулы;

    • pillar.example — файл с примером указания параметров формулы;

    • FORMULA — описание формулы в формате YAML;

  • не обязательные:

    • docs/README.RST — файл с описанием способов применения формулы и входящих в нее состояний;

    • <top_level_dir>/any.sls — другие файлы с расширением .sls, содержащие состояния, которые включены в init.sls или clean.sls директивой include;

    • <top_level_dir>/<any_dir> — другие поддиректории, содержащие файлы с расширением .sls, которые включены в init.sls или clean.sls директивой include;

    • <top_level_dir>/map.jinja — файл, который описывает особенности конфигурации под конкретную ОС или другие статические конфигурации.

Файл FORMULA включает атрибуты формулы:

  • name — имя формулы;

  • os — ОС, поддреживающие формулу;

  • os_family — семейства ОС, поддреживающие формулу;

  • version — версия пакета с формулой, указанная в формате YYYYMM; если в месяце было несколько релизов, то минорный месячный релиз проставляется в атрибуте release;

  • release — выпуск версии; атрибут расширяет версионность формулы, если в месяце было несколько релизов;

  • summary — краткое описание формулы;

  • description — подробное описание формулы;

  • top_level_dir — имя поддиректории, где расположены файлы с расширением .sls.

SLS-файлы формулы составлены в синтаксисе YAML и содержат описания состояний, которые достигает система при применении формулы. Имена SLS-файлов не могут содержать точки, кроме точки между именем и расширением .sls.

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

Добавление формулы в S3-совместимое хранилище, на использование которого настроен сервер управления (master)

Чтобы загрузить формулу на файловый сервер SALT.FILESERVER.S3FS, используйте путь s3://<bucket name>/base/<formula-name>.

Для более подробной информации см. официальную документацию:

Также формулу можно загрузить при помощи API-метода importFormulas. Метод описан в разделе «Метод importFormulas» документа «Описание API».

Создание и импорт конфигурации

Конфигурация описывается в файле формата JSON.

Пример описания конфигурации для формулы по установке Яндекс Браузера:

{
  "displayName": "Яндекс Браузер",
  "description": "Яндекс Браузер — безопасный и быстрый браузер с голосовым помощником.",
  "fullDescription": "Яндекс Браузер — безопасный и быстрый браузер с голосовым помощником.",
  "isApplication": true,
  "categories": [
    "network"
  ],
  "icon": {
    "resourcePath": "specifications/icons/yandex-browser-logo.svg",
    "contentType": "image/svg+xml"
  },
  "images": [
    {
      "resourcePath": "specifications/images/yandex-browser-screen1.webp",
      "contentType": "image/webp"
    }
  ]
}

Где:

  • displayName — (обязательное поле) имя, которое отображается в пользовательском интерфейсе;

  • description — описание конфигурации или ПО;

  • fullDescription — полное описание конфигурации или ПО; для ПО данное описание отображается в качестве подробной информации о нем в магазине приложений;

  • isApplication — (обязательное поле) флаг, который устанавливается для ПО; если это конфигурация, флаг выключен;

  • categories — список категорий;

  • icon — иконка ПО, которая отображается в магазине приложений;

  • images — изображения, которые отображаются на странице с подробным описанием ПО.

После того как вы подготовите JSON-файл с конфигурацией, импортируйте его в кабинете администратора, используя метод createConfiguration. Метод описан в документе «Описание API» в разделе «Метод createSpecification».

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

Добавление версии конфигурации

Версия конфигурации описывается в файле формата JSON.

Пример описания версии конфигурации для формулы по установке Яндекс Браузера:

{
  "displayName": "23.9.1.1023",
  "formulaName": "yandex-browser",
  "releaseDate": "2023-11-14",
  "softwareRequirements": "example",
  "pillarProperty": {
    "lookup": {
      "pkg": {
        "version": "23.9.1.1023-1"
      }
    }
  }
}

Где:

  • displayName — (обязательное поле) имя, которое отображается в пользовательском интерфейсе;

  • formulaName — (обязательное поле) имя формулы, используемой для установки данной версии;

  • releaseDate — (обязательное поле) дата выпуска версии;

  • softwareRequirements — (обязательное поле) требования к установке данной версии;

  • pillarProperty — параметры для переопределения; если поле останется незаполненным, формула версии будет устанавливаться с параметрами по умолчанию.

    В зависимости от назначения формулы можно переопределить некоторые параметры. Параметры, доступные для переопределения, описаны в файле формулы формата YAML pillar.example.

    Пример файла pillar.example для формулы по установке Яндекс Браузера:

    yandex-browser:
  # Переопределите значение map.jinja
  lookup:
    # Укажите параметры пакета
    pkg:
      # Укажите имя пакета для конкретной ОС
      name: yandex-browser-stable
      # Set the specific version of a package. If value is an empty string then used latest version
      version: '23.5.4.685-1'
      # Укажите репозиторий, из которого будет производиться установка. Когда репозиторий будет добавлен (по repo.name),
      # он будет назначен заданному релизу (suite).
      #  Значение может быть пустой строкой
      fromrepo: 'stable'
    # Укажите параметры репозитория
    repo:
      # Укажите имя репозитория, которое будет импортировано в систему. Значение должно быть указано в формате
      # one-line-style (https://manpages.debian.org/unstable/apt/sources.list.5.en.html#THE_DEB_AND_DEB-SRC_TYPES:_GENERAL_FORMAT)
      # без опций. Чтобы задать опции, используйте дополнительные параметры репозитория.
      # Если значение представляет собой пустую строку, то репозиторий не будет импортирован
      name: 'deb http://repo.yandex.ru/yandex-browser/deb stable'
      # Выполните настройку репозитория, чтобы он стал недоступным для поиска и установки пакетов.
      # Значения: True или False
      disabled: False
      # Укажите тип пакетов (компонентов), которые будут установлены из репозитория (например, main, nonfree, ...).
      # Значения параметра comps должны быть заданы в виде списка через запятую
      comps: 'main,contrib,non-free'
      # Укажите имена файлов .list и .gpg. Не могут быть пустой строкой
      conf_name: 'yandex-browser'
      # Укажите key-файл (.gpg) для загрузки на агент. Этот файл может храниться как на сервере управления,
      # так и на серверах HTTP(S) или FTP.
      # Этот файл используется в опции репозитория signed-by. Значение может быть пустой строкой.
      key_file: 'https://repo.yandex.ru/yandex-browser/YANDEX-BROWSER-KEY.GPG'
      # Установите значение True, чтобы декодировать данные key-файла из формата base64 в бинарный
      key_file_dearmor: True
      # Установите полный путь к каталогу ключей на агенте
      key_keyrings_dir: '/etc/apt/keyrings/'
      # Укажите имена для установки пакетов, необходимых для импорта репозитория. Значения должны быть представлены в виде списка через запятую
      required_packages: [ 'gpg' ]

После того как вы подготовите JSON-файл с версией конфигурации, импортируйте его, используя метод createConfigurationVersion. Метод описан в документе «Описание API» в разделе «Метод createSpecificationVersion».

Готовые формулы

Готовые формулы — это формулы, загруженные на сервер управления (master) и готовые к использованию с настройками по умолчанию без какой-либо дополнительной конфигурации. При этом при необходимости можно переопределить в конфигурации параметры, описанные в файле pillar.example (см. описание конкретной формулы).

Такими формулами являются:

Формула ark-formula

Формула для установки пакета Ark (инструмент для сжатия/распаковки графических файлов).

Доступные состояния

Состояние ark

Мета-состояние (состояние, которое включает в себя другие состояния).

Устанавливает пакет Ark из целевого репозитория. Имеет зависимость от ark.repository, ark.package через список include.

Состояние ark.repository

Имеет зависимость от ark.repository.install через список include.

Состояние ark.repository.install

Импортирует репозиторий, если значение repo.name указано в хранилище Pillars (или не пустое по умолчанию) и имеет зависимость от:

  • ark.repository.package.install через список include;

  • ark.repository.key.install через список include и реквизит require.

Состояние ark.repository.package.install

Устанавливает пакеты repo.required_packages(по умолчанию — gpg).

Состояние ark.repository.key.install

Загружает repo.key_file на агент (minion) и декодирует данные файла из формата base64 в бинарный.

Состояние ark.package

Устанавливает пакет Ark.

Состояние ark.clean

Мета-состояние (состояние, которое включает в себя другие состояния).

Отменяет все действия, выполненные в мета-состоянии ark, в обратном порядке, то есть удаляет пакет и удаляет целевой репозиторий (если он был импортирован). Имеет зависимость от ark.package.clean и ark.repository.clean через список include.

Состояние ark.package.clean

Удаляет пакет Ark.

Состояние ark.repository.clean

Удаляет файл конфигурации репозитория. Имеет зависимость от ark.repository.key.clean через список include.

Состояние ark.repository.key.clean

Удаляет Key-файл репозитория.

Пример файла pillar.example
ark:
  # Переопределите значение map.jinja
  lookup:
    # Укажите параметры пакета
    pkg:
      # Укажите имя пакета для конкретной ОС
      name: my-ark
      # Укажите конкретную версию пакета. Если значение представляет собой пустую строку, используется последняя версия
      version: '1.0.0.685-1'
      # Укажите репозиторий, из которого будет производиться установка. Когда репозиторий будет добавлен (по repo.name),
      # он будет назначен заданному релизу (suite).
      #  Значение может быть пустой строкой
      fromrepo: 'stable'
    # Укажите параметры репозитория
    repo:
      # Укажите имя репозитория, которое будет импортировано в систему. Значение должно быть указано в формате
      # one-line-style (https://manpages.debian.org/unstable/apt/sources.list.5.en.html#THE_DEB_AND_DEB-SRC_TYPES:_GENERAL_FORMAT)
      # без опций. Чтобы задать опции, используйте дополнительные параметры репозитория.
      # Если значение представляет собой пустую строку, то репозиторий не будет импортирован
      name: 'deb https://dl.astralinux.ru/astra/stable/1.7_x86-64/repository-main/ 1.7_x86-64'
      # Выполните настройку репозитория, чтобы он стал недоступным для поиска и установки пакетов.
      # Значения: True или False
      disabled: False
      # Укажите тип пакетов (компонентов), которые будут установлены из репозитория (например, main, nonfree, ...).
      # Значения параметра comps должны быть заданы в виде списка через запятую
      comps: 'main,contrib,non-free'
      # Укажите имена файлов .list и .gpg. Не могут быть пустой строкой
      conf_name: 'ark'
      # Укажите key-файл (.gpg) для загрузки на агент. Этот файл может храниться как на сервере управления,
      # так и на серверах HTTP(S) или FTP.
      # Этот файл используется в опции репозитория signed-by. Значение может быть пустой строкой.
      key_file: 'salt://files/keys/MY-ARK-KEY.GPG'
      # Установите значение True, чтобы декодировать данные key-файла из формата base64 в бинарный
      key_file_dearmor: True
      # Установите полный путь к каталогу ключей на агенте
      key_keyrings_dir: '/etc/apt/keyrings/'
      # Укажите имена для установки пакетов, необходимых для импорта репозитория. Значения должны быть представлены в виде списка через запятую
      required_packages: [ 'gpg' ]

Формула google-chrome-formula

Формула для установки веб-браузера Google Chrome.

Доступные состояния

Состояние google-chrome

Мета-состояние (состояние, которое включает в себя другие состояния).

Устанавливает пакет google-chrome из целевого репозитория. Имеет зависимость от google-chrome.repository и google-chrome.package через список include.

Состояние google-chrome.repository

Имеет зависимость от google-chrome.repository.install` через список include.

Состояние google-chrome.repository.install

Импортирует репозиторий, если значение repo.name указано в хранилище Pillars (или не пустое по умолчанию). Имеет зависимость от:

  • google-chrome.repository.package.install через список include;

  • google-chrome.repository.key.install` через список include и реквизит require.

Состояние google-chrome.repository.package.install

Устанавливает пакеты repo.required_packages (по умолчанию — gpg).

Состояние google-chrome.repository.key.install

Загружает repo.key_file на агент (minion) и декодирует данные файла из формата base64 в бинарный.

Состояние google-chrome.package

Устанавливает пакет google-chrome.

Состояние google-chrome.clean

Мета-состояние (состояние, которое включает в себя другие состояния).

Отменяет все действия, выполненные в мета-состоянии google-chrome, в обратном порядке, т.е. удаляет пакет и удаляет целевой репозиторий (если он был импортирован). Имеет зависимость от google-chrome.package.clean и google-chrome.repository.clean через список include.

Состояние google-chrome.package.clean

Удаляет пакет google-chrome.

Состояние google-chrome.repository.clean

Удаляет файл конфигурации репозитория. Имеет зависимость от google-chrome.repository.key.clean через список include.

Состояние google-chrome.repository.key.clean

Удаляет Key-файл репозитория.

Пример файла pillar.example
google-chrome:
  # Переопределите значение map.jinja
  lookup:
    # Укажите параметры пакета
    pkg:
      # Укажите имя пакета для конкретной ОС
      name: google-chrome-stable
      # Set the specific version of a package. If value is an empty string then used latest version
      version: ''
      # Укажите репозиторий, из которого будет производиться установка. Когда репозиторий будет добавлен (по repo.name),
      # он будет назначен заданному релизу (suite).
      #  Значение может быть пустой строкой
      fromrepo: ''
    # Укажите параметры репозитория
    repo:
      # Укажите имя репозитория, которое будет импортировано в систему. Значение должно быть указано в формате
      # one-line-style (https://manpages.debian.org/unstable/apt/sources.list.5.en.html#THE_DEB_AND_DEB-SRC_TYPES:_GENERAL_FORMAT)
      # без опций. Чтобы задать опции, используйте дополнительные параметры репозитория.
      # Если значение представляет собой пустую строку, то репозиторий не будет импортирован
      name: 'deb http://dl.google.com/linux/chrome/deb/ stable main'
      # Выполните настройку репозитория, чтобы он стал недоступным для поиска и установки пакетов.
      # Значения: True или False
      disabled: False
      # Укажите тип пакетов (компонентов), которые будут установлены из репозитория (например, main, nonfree, ...).
      # Значения параметра comps должны быть заданы в виде списка через запятую
      comps: ''
      # Укажите имена файлов .list и .gpg. Не могут быть пустой строкой
      conf_name: 'google-chrome'
      # Укажите key-файл (.gpg) для загрузки на агент. Этот файл может храниться как на сервере управления,
      # так и на серверах HTTP(S) или FTP.
      # Этот файл используется в опции репозитория signed-by. Значение может быть пустой строкой.
      key_file: 'https://dl.google.com/linux/linux_signing_key.pub'
      # Установите значение True, чтобы декодировать данные key-файла из формата base64 в бинарный
      key_file_dearmor: True
      # Установите полный путь к каталогу ключей на агенте
      key_keyrings_dir: '/etc/apt/keyrings/'
      # Укажите имена для установки пакетов, необходимых для импорта репозитория. Значения должны быть представлены в виде списка через запятую
      required_packages: [ 'gpg' ]

Формула okular-formula

Формула для установки ПО Okular (для просмотра документов в различных форматах).

Доступные состояния

Состояние okular

Мета-состояние (состояние, которое включает в себя другие состояния).

Устанавливает пакет okular из целевого репозитория. Имеет зависимость от okular.repository и okular.package через список include.

Состояние okular.repository

Имеет зависимость от okular.repository.install через список include.

Состояние okular.repository.install

Импортирует репозиторий, если значение repo.name указано в хранилище Pillars (или не пустое по умолчанию). Имеет зависимость от:

  • okular.repository.package.install через список include;

  • okular.repository.key.install` через список include и реквизит require.

Состояние okular.repository.package.install

Устанавливает пакеты repo.required_packages (по умолчанию — gpg).

Состояние okular.repository.key.install

Загружает repo.key_file на агент (minion) и декодирует данные файла из формата base64 в бинарный.

Состояние okular.package

Устанавливает пакет okular.

Состояние okular.clean

Мета-состояние (состояние, которое включает в себя другие состояния).

Отменяет все действия, выполненные в мета-состоянии okular, в обратном порядке, т.е. удаляет пакет и удаляет целевой репозиторий (если он был импортирован). Имеет зависимость от okular.package.clean и okular.repository.clean через список include.

Состояние okular.package.clean

Удаляет пакет okular.

Состояние okular.repository.clean

Удаляет файл конфигурации репозитория. Имеет зависимость от okular.repository.key.clean через список include.

Состояние okular.repository.key.clean

Удаляет Key-файл репозитория.

Пример файла pillar.example
okular:
  # Переопределите значение map.jinja
  lookup:
    # Укажите параметры пакета
    pkg:
      # Укажите имя пакета для конкретной ОС
      name: okular
      # Set the specific version of a package. If value is an empty string then used latest version
      version: ''
      # Укажите репозиторий, из которого будет производиться установка. Когда репозиторий будет добавлен (по repo.name),
      # он будет назначен заданному релизу (suite).
      #  Значение может быть пустой строкой
      fromrepo: ''
    # Укажите параметры репозитория
    repo:
      # Укажите имя репозитория, которое будет импортировано в систему. Значение должно быть указано в формате
      # one-line-style (https://manpages.debian.org/unstable/apt/sources.list.5.en.html#THE_DEB_AND_DEB-SRC_TYPES:_GENERAL_FORMAT)
      # без опций. Чтобы задать опции, используйте дополнительные параметры репозитория.
      # Если значение представляет собой пустую строку, то репозиторий не будет импортирован
      name: ''
      # Выполните настройку репозитория, чтобы он стал недоступным для поиска и установки пакетов.
      # Значения: True или False
      disabled: False
      # Укажите тип пакетов (компонентов), которые будут установлены из репозитория (например, main, nonfree, ...).
      # Значения параметра comps должны быть заданы в виде списка через запятую
      comps: ''
      # Укажите имена файлов .list и .gpg. Не могут быть пустой строкой
      conf_name: 'okular'
      # Укажите key-файл (.gpg) для загрузки на агент. Этот файл может храниться как на сервере управления,
      # так и на серверах HTTP(S) или FTP.
      # Этот файл используется в опции репозитория signed-by. Значение может быть пустой строкой.
      key_file: ''
      # Установите значение True, чтобы декодировать данные key-файла из формата base64 в бинарный
      key_file_dearmor: True
      # Установите полный путь к каталогу ключей на агенте
      key_keyrings_dir: '/etc/apt/trusted.gpg.d/'
      # Укажите имена для установки пакетов, необходимых для импорта репозитория. Значения должны быть представлены в виде списка через запятую
      required_packages: [ 'gpg' ]

Формула yandex-browser-formula

Формула для установки веб-браузера Yandex.

Доступные состояния

Состояние yandex-browser

Мета-состояние (состояние, которое включает в себя другие состояния).

Устанавливает пакет yandex-browser из целевого репозитория. Имеет зависимость от yandex-browser.repository и yandex-browser.package через список include.

Состояние yandex-browser.repository

Имеет зависимость от yandex-browser.repository.install через список include.

Состояние yandex-browser.repository.install

Импортирует репозиторий, если значение repo.name указано в хранилище Pillars (или не пустое по умолчанию). Имеет зависимость от:

  • yandex-browser.repository.package.install через список include;

  • yandex-browser.repository.key.install через список include и реквизит require.

Состояние yandex-browser.repository.package.install

Устанавливает пакеты repo.required_packages (по умолчанию — gpg).

Состояние yandex-browser.repository.key.install

Загружает repo.key_file на агент (minion) и декодирует данные файла из формата base64 в бинарный.

Состояние yandex-browser.package

Устанавливает пакет yandex-browser.

Состояние yandex-browser.clean

Мета-состояние (состояние, которое включает в себя другие состояния).

Отменяет все действия, выполненные в мета-состоянии yandex-browser, в обратном порядке, т.е. удаляет пакет и удаляет целевой репозиторий (если он был импортирован). Имеет зависимость от yandex-browser.package.clean и yandex-browser.repository.clean через список include.

Состояние yandex-browser.package.clean

Удаляет пакет yandex-browser.

Состояние yandex-browser.repository.clean

Удаляет файл конфигурации репозитория. Имеет зависимость от yandex-browser.repository.key.clean через список include.

Состояние yandex-browser.repository.key.clean

Удаляет Key-файл репозитория.

Пример файла pillar.example
yandex-browser:
  # Переопределите значение map.jinja
  lookup:
    # Укажите параметры пакета
    pkg:
      # Укажите имя пакета для конкретной ОС
      name: yandex-browser-stable
      # Set the specific version of a package. If value is an empty string then used latest version
      version: '23.5.4.685-1'
      # Укажите репозиторий, из которого будет производиться установка. Когда репозиторий будет добавлен (по repo.name),
      # он будет назначен заданному релизу (suite).
      #  Значение может быть пустой строкой
      fromrepo: 'stable'
    # Укажите параметры репозитория
    repo:
      # Укажите имя репозитория, которое будет импортировано в систему. Значение должно быть указано в формате
      # one-line-style (https://manpages.debian.org/unstable/apt/sources.list.5.en.html#THE_DEB_AND_DEB-SRC_TYPES:_GENERAL_FORMAT)
      # без опций. Чтобы задать опции, используйте дополнительные параметры репозитория.
      # Если значение представляет собой пустую строку, то репозиторий не будет импортирован
      name: 'deb http://repo.yandex.ru/yandex-browser/deb stable'
      # Выполните настройку репозитория, чтобы он стал недоступным для поиска и установки пакетов.
      # Значения: True или False
      disabled: False
      # Укажите тип пакетов (компонентов), которые будут установлены из репозитория (например, main, nonfree, ...).
      # Значения параметра comps должны быть заданы в виде списка через запятую
      comps: 'main,contrib,non-free'
      # Укажите имена файлов .list и .gpg. Не могут быть пустой строкой
      conf_name: 'yandex-browser'
      # Укажите key-файл (.gpg) для загрузки на агент. Этот файл может храниться как на сервере управления,
      # так и на серверах HTTP(S) или FTP.
      # Этот файл используется в опции репозитория signed-by. Значение может быть пустой строкой.
      key_file: 'https://repo.yandex.ru/yandex-browser/YANDEX-BROWSER-KEY.GPG'
      # Установите значение True, чтобы декодировать данные key-файла из формата base64 в бинарный
      key_file_dearmor: True
      # Установите полный путь к каталогу ключей на агенте
      key_keyrings_dir: '/etc/apt/keyrings/'
      # Укажите имена для установки пакетов, необходимых для импорта репозитория. Значения должны быть представлены в виде списка через запятую
      required_packages: [ 'gpg' ]

Формула tigervnc-formula

Формула для установки TigerVNC (сервер виртуальных сетевых вычислений).

Доступные состояния

Состояние tigervnc

Мета-состояние (состояние, которое включает в себя другие состояния).

Устанавливает пакет TigerVNC из целевого репозитория. Имеет зависимость от tigervnc.package через список include.

Состояние tigervnc.package

Устанавливает только пакет TigerVNC.

Состояние tigervnc.clean

Мета-состояние (состояние, которое включает в себя другие состояния).

Отменяет все действия, выполненные в метасостоянии TigerVNC, в обратном порядке, т.е. удаляет пакет и удаляет целевой репозиторий (если он был импортирован). Имеет зависимость от tigervnc.package.clean через список include.

Состояние tigervnc.package.clean

Удаляет пакет TigerVNC.

Пример файла pillar.example
tigervnc:
  # Переопределите значение map.jinja
  lookup:
    # Укажите параметры пакета
    pkg:
      # Укажите имя пакета для конкретной ОС
      name: inno-ira-tigervnc
      # Укажите конкретную версию пакета. Если значение представляет собой пустую строку, используется последняя версия
      version: '1.0.0'
    # Задайте параметры x0vncserver
    x0vncserver_options:
      display: ":0"
      SecurityTypes: TLSPLain
      PlainUsers: "*"
      PAMService: tigervnc
      QueryConnect: 1
      QueryConnectTimeout: 15
      ShowRemoteConnect: 1
      Log: "*:stdout:30"
      HostsFile: "/etc/access-ip-vnc"
      NeverShared: 1
      DisconnectClients: 0
   # Задайте ip-адреса для доступа к tigervnc
   tigervnc_access_ips: []
   # Задайте группы доступа к tigervnc
   tigervnc_access_groups: []

Параметры конфигурации:

  • QueryConnect — вызывает модальное окно у удаленного пользователя, в котором предлагается принять или отклонить входящее соединение.

    Возможные значения:

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

    • 1 — вызывает модальное окно для подтверждения удаленного подключения.

  • QueryConnectTimeout — таймер на предоставление удаленного доступа, по истечении которого запрос автоматически отклоняется, в секундах.

  • ShowRemoteConnect — отображение модального окна, которое информирует об удаленном доступе.

    На дисплее отображается модальное окно с именем, адресом, откуда выполняется подключение, и кнопка Disconnect.

    Возможные значения:

    • 0 — модальное окно скрыто;

    • 1 — отображается модальное окно с информацией.

  • tigervnc_access_ips — IP шлюза, с которого разрешается подключение.

    До адреса необходимо указать символ:

    • + — доступ разрешён;

    • - — доступ запрещён;

    • ? — отправка запроса на разрешение для доступа.

    Например: +199.35.209.1/32.

  • tigervnc_access_groups — группы пользователей, которым разрешено выполнять подключение.

Пользовательские формулы

Пользовательские формулы — это готовые формулы, для которых необходимо переопределить в конфигурации параметры, описанные в файле pillar.example (см. описание конкретной формулы).

Такими формулами являются:

Формула ca-cert-formula

Формула для установки CA-сертификатов.

Для корректного использования формулы необходимо создать пользовательскую конфигурацию и переопределить параметры по умолчанию, описанные в файле pillar.example.
Доступные состояния

Состояние ca-cert

Мета-состояние (состояние, которое включает в себя другие состояния).

Устанавливает сертификаты в системном хранилище и хранилище профилей пользователей (NSSDB). Имеет зависимость от ca-cert.sys, ca-cert.user через список include.

Состояние ca-cert.sys

Имеет зависимость от ca-cert.sys.install через список include.

Состояние ca-cert.sys.install

Запускает команду sys.certs_update_cmd для обновления системных сертификатов и имеет зависимость от ca-cert.sys.certs.files через список include и реквизит onchanges.

Состояние ca-cert.sys.certs.files

Сохраняет на диске (в директории certs.dest_dir) файлы сертификата из списка certs.files.

Состояние ca-cert.user

Имеет зависимость от ca-cert.user.install через список include.

Состояние ca-cert.user.install

Имеет зависимость от ca-cert.user.nssdb через список include.

Состояние ca-cert.user.nssdb

Имеет зависимость от ca-cert.user.nssdb.update через список include.

Состояние ca-cert.user.nssdb.update

Добавляет сертификаты в хранилище профилей пользователей (NSSDB) и имеет зависимость от:

  • ca-cert.user.nssdb.create через список include и реквизит require;

  • ca-cert.user.certs.files через список include и реквизит onchanges.

Если в хранилище Pillar нет пользователей в user.usernames, пользователи будут настраиваться по имени каталога в /home.

Состояние ca-cert.user.nssdb.create

Создает хранилище сертификатов пользователя (NSSDB) в домашней директории пользователя и имеет зависимость от ca-cert.user.package.instal через список include и реквизит require. Если в хранилище Pillar в поле user.usernames не указано ни одного пользователя, пользователи будут настраиваться по имени каталога в /home.

Состояние ca-cert.user.package.install

Устанавливает пакет cacert.user.pkg.name (по умолчанию — libnss3-tools).

Состояние ca-cert.user.certs.files

Сохраняет на диске (в директории certs.dest_dir_user) файлы сертификата из списка certs.files.

Состояние ca-cert.clean

Мета-состояние (состояние, которое включает в себя другие состояния).

Удаляет сертификаты их системного хранилища и хранилища профилей пользователей (NSSDB). Имеет зависимость от ca-cert.sys.clean, ca-cert.user.clean через список include.

Состояние ca-cert.sys.clean

Запускает команду sys.certs_update_cmd для обновления системных сертификатов и имеет зависимость от ca-cert.sys.certs.clean через список include и реквизит onchanges.

Состояние ca-cert.sys.certs.clean

Удаляет с диска (директория certs.dest_dir) файлы сертификата из списка certs.files.

Состояние ca-cert.user.clean

Имеет зависимость от ca-cert.user.nssdb.clean, ca-cert.user.package.clean через список включения.

Состояние ca-cert.user.nssdb.clean

Удаляет сертификаты из хранилища профилей пользователей (NSSDB) и имеет зависимость от ca-cert.user.certs.clean через список include и реквизит require.

Состояние ca-cert.user.certs.clean

Удаляет с диска (директория certs.dest_dir_user) файлы сертификата из списка certs.files.

Состояние ca-cert.user.package.clean

Удаляет пакет cacert.user.pkg.name (по умолчанию — libnss3-tools).

Пример файла pillar.example
ca-cert:
  # Переопределите значение map.jinja
  lookup:
    # Укажите параметры сертификатов
    certs:
      # Укажите список имен файлов сертификатов. Значения не могут быть пустыми
      #  Значения должны быть указаны в виде списка через запятую
      files: [
        "my_ca_1.crt",
        "my_ca_2.crt",
      ]
      # Укажите полный путь к каталогу, в котором хранятся файлы сертификатов,
      #  на файловом сервере
      source_dir: "salt://files/cacerts/"
      # Укажите полный путь к каталогу для системных сертификатов на агенте
      dest_dir: "/usr/local/share/ca-certificates/"
      # Укажите полный путь к каталогу для общих сертификатов пользователей на агенте
      dest_dir_user: "/usr/local/share/ca-certificates-nssdb/"
    # Укажите некоторые параметры системы
    sys:
      # Укажите команду, которая будет выполняться для обновления системных сертификатов
      certs_update_cmd: "update-ca-certificates --fresh"
    # Укажите некоторые параметры пользователей
    user:
      # Укажите список имен пользователей для обновления сертификатов. Если пользователи
      # не заданы, пользователи будут выбраны по имени каталога в /home
      usernames: [
        "username_1",
        "username_1",
      ]
Изменение значений параметров по умолчанию

  1. Извлеките формулу ca-cert-formula из архива.

    $ tar -xvf ~/Downloads/inno-lcm-salt-formulas-X.Y.Z.tar.gz \
    --strip-components 3 \
    -C ~/ \
    ./formulas/ca-cert-formula/ca-cert
$ cd ~/ca-cert

  2. Создайте директорию files и скопируйте в нее необходимые сертификаты.

    В качестве примера используются сертификаты ЦС НУЦ Минцифры:

    $ ls ./files/
russian_trusted_root_ca_pem.crt  russian_trusted_sub_ca_pem.crt

  3. Измените файл map.jinja(словарь со значениями по умолчанию):

    1. Измените значение default.certs.source_dir, указав директорию files, созданную в формуле.

    2. Измените значение default.certs.files, указав в списке имена файлов в директории files.

    3. Оставьте пустым списком значение default.user.usernames — это будет означать, что сертификаты будут установлены для всех пользователей, для которых создана папка в каталоге /home/).

    4. Удалите все значения, относящиеся к ОС Debian.

      {% set mapdata = salt['grains.filter_by']({
    'default': {
        'certs': {
            'files': [
                'russian_trusted_root_ca_pem.crt',
                'russian_trusted_sub_ca_pem.crt',
            ],
            'source_dir': 'salt://ca-cert/files/',
            'dest_dir': '/usr/local/share/ca-certificates/',
            'dest_dir_user': '/usr/local/share/ca-certificates-nssdb/',
        },
        'sys': {
            'certs_update_cmd': 'update-ca-certificates --fresh',
        },
         'user': {
            'usernames': [
            ],
            'pkg': {
                'name': 'libnss3-tools',
            },
        },
    },
}, merge=salt['pillar.get']('ca-cert:lookup'), base='default') %}

После переопределения значений по умолчанию, следуйте инструкциям по работе с формулой в разделе «Работа формулами».

Формула deb-repo-formula

Формула для добавления пользовательского репозитория с Deb-пакетами.

Доступные состояния

Состояние deb-repo

Мета-состояние (состояние, которое включает в себя другие состояния).

Добавляет и настраивает Deb-репозиторий. Имеет зависимость от deb-repo.install через список include.

Состояние deb-repo.install

Импортирует репозиторий, если значение name указано в хранилище Pillars (или не пустое по умолчанию).

Состояние deb-repo.key.install

Загружает deb-repo.key_file на агент (minion) и декодирует данные файла из формата base64 в бинарный.

Состояние deb-repo.clean

Удаляет файл конфигурации репозитория. Имеет зависимость от deb-repo.key.clean через список include.

Состояние deb-repo.key.clean

Удаляет Key-файл репозитория.

Пример файла pillar.example
deb-repo:
  # Переопределите значение map.jinja
  lookup:
    # Укажите имя репозитория, которое будет импортировано в систему. Значение должно быть указано в формате
    # one-line-style (https://manpages.debian.org/unstable/apt/sources.list.5.en.html#THE_DEB_AND_DEB-SRC_TYPES:_GENERAL_FORMAT)
    #  с опциями в квадратных скобках ([]). Опции используются для установки дополнительных параметров репозитория,
    # например, `signed-by`, `trusted`, `allow-insecure`.
    #  Опция настройки архитектуры ('arch') будет добавлена автоматически из параметра grain на агенте
    name: 'deb [signed-by=/etc/apt/keyrings/repo-key.gpg trusted=yes] https://dl.astralinux.ru/astra/stable/1.7_x86-64/repository-main/ 1.7_x86-64'
    # Выполните настройку репозитория, чтобы он стал недоступным для поиска и установки пакетов.
    # Значения: True или False
    disabled: False
    # Укажите тип пакетов (компонентов), которые будут установлены из репозитория (например, main, nonfree, ...).
    # Значения параметра comps должны быть заданы в виде списка через запятую
    comps: 'main,contrib,non-free'
    # Укажите имена файлов .list и .gpg. Не могут быть пустой строкой
    conf_name: 'repository-main'
    # Укажите key-файл (.gpg) для загрузки на агент. Этот файл может храниться как на сервере управления,
    # так и на серверах HTTP(S) или FTP.
    # Этот файл используется в опции репозитория signed-by. Значение может быть пустой строкой.
    # Отсутствие значения означает, что key-файл не будет импортирован и не будет использоваться.
    # Если используется key-файл, необходимо добавить опцию в формате 'signed-by={{ key_keyrings_dir }}{{ conf_name }}.gpg', example 'signed-by=/etc/apt/keyrings/repository-main.gpg'
    key_file: ''
    # Установите значение True, чтобы декодировать данные key-файла из формата base64 в бинарный
    key_file_dearmor: False
    # Установите полный путь к каталогу ключей на агенте
    key_keyrings_dir: '/etc/apt/keyrings/'
    # Укажите имена для установки пакетов, необходимых для импорта репозитория. Значения должны быть представлены в виде списка через запятую
    required_packages: [ 'gpg' ]

Формула web-mail-formula

Формула для установки Web Mail.

Доступные состояния

Состояние web-mail

Мета-состояние (состояние, которое включает в себя другие состояния).

Устанавливает ссылку на Web Mail. Имеет зависимость от web-mail.install через список include.

Состояние web-mail.install

Создает ссылку (файл web-mail.desktop) на Web Mail на рабочем столе пользователя (папка ~/Desktop).

Если в хранилище Pillar в поле user.usernames не указано ни одного пользователя, пользователи будут настраиваться по имени каталога в /home.

Если в полях link.name и link.url значения не заданы, формула не будет выполнена, и отобразится соответствующее уведомление.

Состояние web-mail.clean

Удаляет ссылку (файл web-mail.desktop) c рабочего стола пользователя (папка ~/Desktop).

Если в хранилище Pillar в поле user.usernames не указано ни одного пользователя, пользователи будут настраиваться по имени каталога в /home.

Если в полях link.name и link.url значения не заданы, формула не будет выполнена, и отобразится соответствующее уведомление.

Пример файла pillar.example
web-mail:
  # Переопределите значение map.jinja
  lookup:
    # Укажите параметры ссылки
    link:
      # Укажите название ссылки на рабочем столе
      name: "Link to My Corp Mail"
      # Укажите URL доступа
      url: "https://mail.yandex.ru/"
      # Задайте имя (или путь к файловой системе агента) иконки, которая будет использоваться для отображения
      # на рабочем столе Значение по умолчанию: "mail"
      icon: "/path/to/icon"
    # Задайте параметры пользователей
    user:
      # Укажите список имен пользователей для обновления сертификатов. Если пользователи
      # не заданы, пользователи будут выбраны по имени каталога в /home
      usernames: [
        "username_1",
        "username_2",
      ]

Формулы-шаблоны

Формулы-шаблоны используются в качестве примера для создания собственных формул подобного типа. Такими формулами являются:

Формула tpl-shortcut-formula

Формула-шаблон для добавления ярлыка приложения, url-адреса и символической ссылки (symlink) на рабочий стол пользователя.

Доступные состояния

Состояние tpl-shortcut

Мета-состояние (состояние, которое включает в себя другие состояния).

Устанавливает ссылку на Web Mail. Имеет зависимость от tpl-shortcut.install через список include.

Состояние tpl-shortcut.install

Создает символическую ссылку или файл Desktop Entry (приложение, ссылку) на рабочем столе пользователя (папка ~/Desktop).

Если в хранилище Pillar в поле user.usernames не указано ни одного пользователя, пользователи будут настраиваться по имени каталога в /home.

Если в полях link.name и link.url значения не заданы, формула не будет выполнена, и отобразится соответствующее уведомление.

Состояние tpl-shortcut.clean

Удаляет символическую ссылку или файл Desktop Entry (приложение, ссылку) c рабочего стола пользователя (папка ~/Desktop).

Если в хранилище Pillar в поле user.usernames не указано ни одного пользователя, пользователи будут настраиваться по имени каталога в /home.

Если в полях link.name и link.url значения не заданы, формула не будет выполнена, и отобразится соответствующее уведомление.

Пример файла pillar.example
tpl-shortcut:
  # Переопределите значение map.jinja
  lookup:
    # Переопределите параметры ссылки на приложение
    application:
      # Задайте имя файла ссылки на рабочий стол
      name: "bash_application"
    # Задайте параметры ссылки
    link:
      # Задайте имя файла ссылки на рабочий стол
      name: "ya-ru_link"
    # Задайте параметры ссылки
    symlink:
      # Задайте имя файла символической ссылки на рабочий стол
      name: "distro-info_debian_symlink"
      # Задайте полный путь к целевому файлу в файловой системе агента
      target: "/usr/share/distro-info/debian.csv"
    # Задайте параметры пользователей
    user:
      # Укажите список имен пользователей для обновления сертификатов. Если пользователи
      # не заданы, пользователи будут выбраны по имени каталога в /home
      usernames: [
        "username_1",
        "username_2",
      ]
Написание формулы типа tpl-shortcut-formula

  1. Скопируйте формулу-шаблон (tpl-shortcut) в новую директорию с новым названием (my-shortcut):

    $ tar -xvf ~/Downloads/inno-lcm-salt-formulas-0.9.0.tar.gz \
    --strip-components 3 \
    -C ~/ \
    ./formulas/tpl-shortcut-formula/tpl-shortcut
$ cp -R ~/tpl-shortcut/ ~/my-shortcut && cd ~/my-shortcut

  2. Измените файл состояний install.sls (создание ярлыков):

    1. Измените ID состояний.

      Рекомендуется для соблюдения уникальности придерживаться именования вида: formula-name-state-name-other-state-name-module-function-some-id. Например, ID состояния для создания symlink будет выглядеть как: my-shortcut-install-file-symlink-{{ username }}-symlink.

    2. Измените значение аргумента contents для функции из состояния: my-shortcut-install-file-managed-{{ username }}-application (ярлык для приложения). Например, имя (Name), запускаемую программу (Exec) и иконку ярлыка (Icon).

    3. Измените значение аргумента contents для функции из состояния my-shortcut-install-file-managed-{{ username }}-link (ярлык для url). Например, имя (Name) и url-адрес (URL).

      # -*- coding: utf-8 -*-
# vim: ft=sls

{#- Get the `tplroot` from `tpldir` #}
{%- set tplroot = tpldir.split('/')[0] %}
{%- from tplroot ~ "/map.jinja" import mapdata as tplshortcut with context %}
{%- from tplroot ~ "/_usernames_lib.sls" import usernames with context %}

{#- Create application link #}
{%- if tplshortcut.application.name %}
{%- for username in usernames  %}

my-shortcut-install-file-managed-{{ username }}-application:
  file.managed:
    - name: /home/{{ username }}/Desktop/{{ tplshortcut.application.name }}.desktop
    - user: {{ username }}
    - group: {{ username }}
    - makedirs: True
    - contents: |
        [Desktop Entry]
        Type=Application
        Name=Run bash manpage
        Exec=man bash
        Terminal=true
        Icon=dictionary

{%- endfor %}
{%- endif %}

{#- Create url link #}
{%- if tplshortcut.link.name %}
{%- for username in usernames  %}

my-shortcut-install-file-managed-{{ username }}-link:
  file.managed:
    - name: /home/{{ username }}/Desktop/{{ tplshortcut.link.name }}.desktop
    - user: {{ username }}
    - group: {{ username }}
    - makedirs: True
    - contents: |
        [Desktop Entry]
        Type=Link
        Name=Love DuckDuckGo!
        URL=https://duckduckgo.com

{%- endfor %}
{%- endif %}

{#- Create symlink #}
{%- if tplshortcut.symlink.name %}
{%- for username in usernames  %}

my-shortcut-install-file-symlink-{{ username }}-symlink:
  file.symlink:
    - name: /home/{{ username }}/Desktop/{{ tplshortcut.symlink.name }}
    - target: {{ tplshortcut.symlink.target }}
    - user: {{ username }}
    - group: {{ username }}
    - makedirs: True

{%- endfor %}
{%- endif %}

  3. В файле состояний clean.sls (удаление ярлыков) измените ID состояний:

    # -*- coding: utf-8 -*-
# vim: ft=sls

{#- Get the `tplroot` from `tpldir` #}
{%- set tplroot = tpldir.split('/')[0] %}
{%- from tplroot ~ "/map.jinja" import mapdata as tplshortcut with context %}
{%- from tplroot ~ "/_usernames_lib.sls" import usernames with context %}

{#- Delete application link #}
{%- if tplshortcut.application.name %}
{%- for username in usernames  %}

my-shortcut-install-file-managed-{{ username }}-application:
  file.absent:
    - name: /home/{{ username }}/Desktop/{{ tplshortcut.application.name }}.desktop

{%- endfor %}
{%- endif %}

{#- Delete url link #}
{%- if tplshortcut.link.name %}
{%- for username in usernames  %}

my-shortcut-install-file-managed-{{ username }}-link:
  file.absent:
    - name: /home/{{ username }}/Desktop/{{ tplshortcut.link.name }}.desktop

{%- endfor %}
{%- endif %}

{#- Delete symlink #}
{%- if tplshortcut.symlink.name %}
{%- for username in usernames  %}

my-shortcut-install-file-symlink-{{ username }}-symlink:
  file.absent:
    - name: /home/{{ username }}/Desktop/{{ tplshortcut.symlink.name }}

{%- endfor %}
{%- endif %}

  4. Измените файл map.jinja(словарь со значениями по умолчанию):

    1. Измените имя ключа для словаря в хранилище Pillar, используемого для динамического переопределения значений по умолчанию.

      Рекомендуется для соблюдения уникальности придерживаться именования вида: formula-name:lookup. Например, my-shortcut:lookup.

    2. Измените значение application.name.

    3. Измените значение link.name.

    4. Измените значения symlink.name и symlink.target.

      {% set mapdata = salt['grains.filter_by']({
    'default': {
        'application': {
            'name': 'man_application',
        },
        'link': {
            'name': 'duckduckgo_link',
        },
        'symlink': {
            'name': 'distro-info_ubuntu_symlink',
            'target': '/usr/share/distro-info/ubuntu.csv'
        },
        'user': {
            'usernames': [
            ],
        },
    },
}, merge=salt['pillar.get']('my-shortcut:lookup'), base='default') %}
После того как формула будет написана, следуйте инструкциям по работе с формулой в разделе «Работа с формулами».

Формула tpl-script-formula

Формула-шаблон для выполнения скриптов.

Доступные состояния

Состояние tpl-script

Мета-состояние (состояние, которое включает в себя другие состояния).

Выполняет скрипт. Имеет зависимость от tpl-script.run через список include.

Состояние tpl-script.run

Выполняет скрипт test_script.sh, если файл /tmp/test_script-unless отсутствует в файловой системе агента (minion). The running script creates /tmp/test_script-unless file with TEST_ENV shell variable content.

Состояние tpl-script.clean

Удаляет файл /tmp/test_script-unless на агенте (minion).

Пример файла pillar.example
tpl-script:
  # Переопределите значение map.jinja
  lookup:
    # Задайте имя для файла скрипта, который хранится в {{ tpldir }}/files/
    file_name: "test_script.sh"
     # Задайте оболочку, которая будет использоваться для выполнения скрипта
    shell: "/bin/sh"
     # Задайте переменные env
    env:
      test_env: "HELLO WORLD!"

Написание формулы типа tpl-script-formula

  1. Скопируйте формулу-шаблон (tpl-script) в новую директорию с новым названием (my-script).

    $ tar -xvf ~/Downloads/inno-lcm-salt-formulas-0.10.0.tar.gz \
    --strip-components 3 \
    -C ~/ \
    ./formulas/tpl-script-formula/tpl-shortcut
$ cp -R ~/tpl-script/ ~/my-script && cd ~/my-script

  2. Переименуйте файл ./files/test_script.sh в ./files/my-new-script.sh и затем измените его содержимое. Файл будет выглядеть следующим образом:

    #!/bin/bash
#
echo "Working hard..."
echo "True" > /var/local/my-script.run.id

# writing the state line
echo  # an empty line here so the next line will be the last.
echo "changed=yes comment='Created /var/local/my-script.run.id file' whatever=123"

  3. Измените файл состояний run.sls (запуск скрипта):

    1. Измените ID состояний.

    2. Удалите аргумент env и его значения.

    3. Измените значение аргумента unless, указав в проверке файл, создаваемый в скрипте, таким образом, исключив повторный запуск скрипта при очередном применении формулы.

      # -*- coding: utf-8 -*-
# vim: ft=sls

{#- Get the `tplroot` from `tpldir` #}
{%- set tplroot = tpldir.split('/')[0] %}
{%- from tplroot ~ "/map.jinja" import mapdata as tplscript with context %}

{#- Run custom script #}
{%- if tplscript.file_name %}

my-script-run-cmd-script:
  cmd.script:
    - source: salt://{{ tpldir }}/files/{{ tplscript.file_name }}
    - cwd: /
    - shell: {{ tplscript.shell }}
    - unless: "test -f /var/local/my-script.run.id"

{%- endif %}

  4. Измените файл состояний clean.sls (удаление проверочного файла):

    1. Измените ID состояний.

    2. Измените значение аргумента name.

      # -*- coding: utf-8 -*-
# vim: ft=sls

{#- Get the `tplroot` from `tpldir` #}
{%- set tplroot = tpldir.split('/')[0] %}
{%- from tplroot ~ "/map.jinja" import mapdata as tplscript with context %}

{#- Delete symlink #}
{%- if tplscript.file_name %}

my-script-clean-file-absent:
  file.absent:
    - name: /var/local/my-script.run.id

{%- endif %}

  5. Измените файл map.jinja(словарь со значениями по умолчанию):

    1. Измените имя ключа для словаря в хранилище Pillar, используемого для динамического переопределения значений по умолчанию.

    2. Измените значение file_name, указав имя созданного скрипта.

    3. Удалите env.

      {% set mapdata = salt['grains.filter_by']({
    'default': {
        'file_name': 'my-new-script.sh',
        'shell': '/bin/sh',
    },
}, merge=salt['pillar.get']('my-script:lookup'), base='default') %}
После того как формула будет написана, следуйте инструкциям по работе с формулой в разделе «Работа с формулами».

Формула tpl-yb-settings-formula

Формула-шаблон для управления настройками веб-браузера Yandex.

Доступные состояния

Состояние tpl-yb-settings

Мета-состояние (состояние, которое включает в себя другие состояния).

Устанавливает политики Яндекс-браузера. Имеет зависимость от tpl-yb-settings.install через список include.

Состояние tpl-yb-settings.install

Загружает управляемые и рекомендуемые файлы политик в файловую системы агента (minion).

Состояние tpl-yb-settings.clean

Удаляет управляемые и рекомендуемые файлы политик из файловой системы агента (minion).

Пример файла pillar.example
tpl-yb-settings:
  # Override map.jinja
  lookup:
    # Переопределите значение map.jinja
    policies:
      # Задайте параметры управляемых политик
      managed:
        # Задайте имя файла с управляемыми политиками (.json), который будет помещен в файловую систему агента
        name: "managed_policies"
        # Задайте имя файла с управляемыми политиками (.json) для загрузки на агент, этот файл может быть помещен как на
        # сервере управления, так и на сервере HTTP(S) или FTP server. Значение может быть пустой строкой
        source: "salt://tpl-yb-settings/files/managed_policies.json"
      # Задайте параметры рекомендуемых политик
      recommended:
        # SЗадайте имя файла с рекомендуемыми политиками (.json), который будет помещен в файловую систему агента
        name: "recommended_policies"
        # Задайте имя файла с рекомендуемыми политиками (.json) для загрузки на агент, этот файл может быть помещен как на
        # сервере управления, так и на сервере HTTP(S) или FTP server. Значение может быть пустой строкой
        source: "salt://tpl-yb-settings/files/recommended_policies.json"
Написание формулы типа tpl-yb-settings

  1. Скопируйте формулу-шаблон (tpl-yb-settings) в новую директорию с новым названием (my-yb-settings):

    $ tar -xvf ~/Downloads/inno-lcm-salt-formulas-0.11.0.tar.gz \
    --strip-components 3 \
    -C ~/ \
    ./formulas/tpl-yb-settings-formula/tpl-yb-settings
$ cp -R ~/tpl-yb-settings/ ~/my-yb-settings && cd ~/my-yb-settings

  2. Измените файл ./files/managed_policies.json, добавив в него политики, которые нужно принудительно применить на устройствах пользователей.

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

    {
    "URLBlocklist": ["*"],
    "URLAllowlist": [
      "browser://policy",
      "duckduckgo.com",
      "https://yandex.ru/pogoda",
      "file://*"
    ]
}

  3. Измените файл ./files/recommended_policies.json, добавив в него политики:

    {
    "HomepageLocation": "https://duckduckgo.com"
}

  4. В файле состояний install.sls (установка политик) измените ID состояний:

    # -*- coding: utf-8 -*-
# vim: ft=sls

{#- Get the `tplroot` from `tpldir` #}
{%- set tplroot = tpldir.split('/')[0] %}
{%- from tplroot ~ "/map.jinja" import mapdata as tplybsettings with context %}

{%- if tplybsettings.policies.managed.source %}

my-yb-settings-install-file-managed-policies-managed:
  file.managed:
    - name: "/etc/opt/yandex/browser/policies/managed/{{ tplybsettings.policies.managed.name }}.json"
    - source: {{ tplybsettings.policies.managed.source }}
    - skip_verify: True
    - makedirs: True

{%- endif %}

{%- if tplybsettings.policies.recommended.source %}

my-yb-settings-install-file-managed-policies-recommended:
  file.managed:
    - name: "/etc/opt/yandex/browser/policies/recommended/{{ tplybsettings.policies.recommended.name }}.json"
    - source: {{ tplybsettings.policies.recommended.source }}
    - skip_verify: True
    - makedirs: True

{%- endif %}

  5. В файле состояний clean.sls (удаление политик) измените ID состояний:

    # -*- coding: utf-8 -*-
# vim: ft=sls

{#- Get the `tplroot` from `tpldir` #}
{%- set tplroot = tpldir.split('/')[0] %}
{%- from tplroot ~ "/map.jinja" import mapdata as tplybsettings with context %}

{%- if tplybsettings.policies.managed.source %}

my-yb-settings-clean-file-absent-policies-managed:
  file.absent:
    - name: "/etc/opt/yandex/browser/policies/managed/{{ tplybsettings.policies.managed.name }}.json"

{%- endif %}

{%- if tplybsettings.policies.recommended.source %}

my-yb-settings-clean-file-absent-policies-recommended:
  file.absent:
    - name: "/etc/opt/yandex/browser/policies/recommended/{{ tplybsettings.policies.recommended.name }}.json"

{%- endif %}

  6. Измените файл map.jinja(словарь со значениями по умолчанию):

    1. Измените имя ключа для словаря в хранилище Pillar, используемого для динамического переопределения значений по умолчанию.

    2. Измените значения policies.managed.source и policies.recommended.source и расположение файлов политик file_name.

      {% set mapdata = salt['grains.filter_by']({
    'default': {
        'policies': {
            'managed': {
                'name': 'managed_policies',
                'source': 'salt://my-yb-settings/files/managed_policies.json',
            },
            'recommended': {
                'name': 'recommended_policies',
                'source': 'salt://my-yb-settings/files/recommended_policies.json',
            },
        },
    },
}, merge=salt['pillar.get']('my-yb-settings:lookup'), base='default') %}
После того как формула будет написана, следуйте инструкциям по работе с формулой в разделе «Работа с формулами».

Формула tpl-yb-settings-formula

Формула-шаблон для управления настройками веб-браузера Yandex.

Доступные состояния

Состояние tpl-yb-settings

Мета-состояние (состояние, которое включает в себя другие состояния).

Устанавливает политики Яндекс-браузера. Имеет зависимость от tpl-yb-settings.install через список include.

Состояние tpl-yb-settings.install

Загружает управляемые и рекомендуемые файлы политик в файловую системы агента (minion).

Состояние tpl-yb-settings.clean

Удаляет управляемые и рекомендуемые файлы политик из файловой системы агента (minion).

Пример файла pillar.example
tpl-yb-settings:
  # Override map.jinja
  lookup:
    # Переопределите значение map.jinja
    policies:
      # Задайте параметры управляемых политик
      managed:
        # Задайте имя файла с управляемыми политиками (.json), который будет помещен в файловую систему агента
        name: "managed_policies"
        # Задайте имя файла с управляемыми политиками (.json) для загрузки на агент, этот файл может быть помещен как на
        # сервере управления, так и на сервере HTTP(S) или FTP server. Значение может быть пустой строкой
        source: "salt://tpl-yb-settings/files/managed_policies.json"
      # Задайте параметры рекомендуемых политик
      recommended:
        # SЗадайте имя файла с рекомендуемыми политиками (.json), который будет помещен в файловую систему агента
        name: "recommended_policies"
        # Задайте имя файла с рекомендуемыми политиками (.json) для загрузки на агент, этот файл может быть помещен как на
        # сервере управления, так и на сервере HTTP(S) или FTP server. Значение может быть пустой строкой
        source: "salt://tpl-yb-settings/files/recommended_policies.json"
Написание формулы типа tpl-yb-settings

  1. Скопируйте формулу-шаблон (tpl-yb-settings) в новую директорию с новым названием (my-yb-settings):

    $ tar -xvf ~/Downloads/inno-lcm-salt-formulas-0.11.0.tar.gz \
    --strip-components 3 \
    -C ~/ \
    ./formulas/tpl-yb-settings-formula/tpl-yb-settings
$ cp -R ~/tpl-yb-settings/ ~/my-yb-settings && cd ~/my-yb-settings

  2. Измените файл ./files/managed_policies.json, добавив в него политики, которые нужно принудительно применить на устройствах пользователей.

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

    {
    "URLBlocklist": ["*"],
    "URLAllowlist": [
      "browser://policy",
      "duckduckgo.com",
      "https://yandex.ru/pogoda",
      "file://*"
    ]
}

  3. Измените файл ./files/recommended_policies.json, добавив в него политики:

    {
    "HomepageLocation": "https://duckduckgo.com"
}

  4. В файле состояний install.sls (установка политик) измените ID состояний:

    # -*- coding: utf-8 -*-
# vim: ft=sls

{#- Get the `tplroot` from `tpldir` #}
{%- set tplroot = tpldir.split('/')[0] %}
{%- from tplroot ~ "/map.jinja" import mapdata as tplybsettings with context %}

{%- if tplybsettings.policies.managed.source %}

my-yb-settings-install-file-managed-policies-managed:
  file.managed:
    - name: "/etc/opt/yandex/browser/policies/managed/{{ tplybsettings.policies.managed.name }}.json"
    - source: {{ tplybsettings.policies.managed.source }}
    - skip_verify: True
    - makedirs: True

{%- endif %}

{%- if tplybsettings.policies.recommended.source %}

my-yb-settings-install-file-managed-policies-recommended:
  file.managed:
    - name: "/etc/opt/yandex/browser/policies/recommended/{{ tplybsettings.policies.recommended.name }}.json"
    - source: {{ tplybsettings.policies.recommended.source }}
    - skip_verify: True
    - makedirs: True

{%- endif %}

  5. В файле состояний clean.sls (удаление политик) измените ID состояний:

    # -*- coding: utf-8 -*-
# vim: ft=sls

{#- Get the `tplroot` from `tpldir` #}
{%- set tplroot = tpldir.split('/')[0] %}
{%- from tplroot ~ "/map.jinja" import mapdata as tplybsettings with context %}

{%- if tplybsettings.policies.managed.source %}

my-yb-settings-clean-file-absent-policies-managed:
  file.absent:
    - name: "/etc/opt/yandex/browser/policies/managed/{{ tplybsettings.policies.managed.name }}.json"

{%- endif %}

{%- if tplybsettings.policies.recommended.source %}

my-yb-settings-clean-file-absent-policies-recommended:
  file.absent:
    - name: "/etc/opt/yandex/browser/policies/recommended/{{ tplybsettings.policies.recommended.name }}.json"

{%- endif %}

  6. Измените файл map.jinja(словарь со значениями по умолчанию):

    1. Измените имя ключа для словаря в хранилище Pillar, используемого для динамического переопределения значений по умолчанию.

    2. Измените значения policies.managed.source и policies.recommended.source и расположение файлов политик file_name.

      {% set mapdata = salt['grains.filter_by']({
    'default': {
        'policies': {
            'managed': {
                'name': 'managed_policies',
                'source': 'salt://my-yb-settings/files/managed_policies.json',
            },
            'recommended': {
                'name': 'recommended_policies',
                'source': 'salt://my-yb-settings/files/recommended_policies.json',
            },
        },
    },
}, merge=salt['pillar.get']('my-yb-settings:lookup'), base='default') %}
После того как формула будет написана, следуйте инструкциям по работе с формулой в разделе «Работа с формулами».

Формула tpl-group-members-formula

Формула-шаблон для управления членством в локальных группах.

Доступные состояния

Состояние tpl-group-members

Мета-состояние (состояние, которое включает в себя другие состояния).

Создает и управляет локальными настройками групп. Имеет зависимость от tpl-group-members.install через список include.

Состояние tpl-group-members.install

Создает group_name (если эта группа отсутствует на агенте (minion)) и изменяет настройки группы.

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

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

  • если для параметра change установлено значение "", заменяет существующих членов группы списком новых участников.

Состояние tpl-group-members.clean

Удаляет группу group_name на агенте (minion).

Пример файла pillar.example
tpl-group-members:
  # Переопределите значение map.jinja
  lookup:
    # Задайте имя группы
    group_name: "sudo"
    # Задайте id для группы;
    # Если оставить поле пустым, группе автоматически будет присвоен следующий свободный идентификатор.
    gid: ""
    # Укажите, является ли группа системной группой.
    # Это опция '-r' в команде 'groupadd`
    system: false
    # Задайте действие для списка пользователей: добавить (`add`), удалить(`del`) или заменить ("").
    change: ""
    # Задайте список пользователей
    users: [
        "user1",
        "user2",
    ]
Написание формулы типа tpl-group-members-formula

  1. Скопируйте формулу-шаблон (tpl-group-members) в новую директорию с новым названием (my-group-members).

    $ tar -xvf ~/Downloads/inno-lcm-salt-formulas-X.Y.Z.tar.gz \
    --strip-components 3 \
    -C ~/ \
    ./formulas/tpl-yb-settings-formula/tpl-group-members
$ cp -R ~/tpl-group-members/ ~/my-group-members && cd ~/my-group-members

  2. В файле состояний install.sls (создание и настройка группы) измените ID состояний:

    # -*- coding: utf-8 -*-
# vim: ft=sls

{#- Get the `tplroot` from `tpldir` #}
{%- set tplroot = tpldir.split('/')[0] %}
{%- from tplroot ~ "/map.jinja" import mapdata as tplgroupmembers with context %}

{%- if tplgroupmembers.group_name %}

my-group-members-group-present:
  group.present:
    - name: {{ tplgroupmembers.group_name }}
    {%- if tplgroupmembers.gid %}
    - gid: {{ tplgroupmembers.gid }}
    {%- endif %}
    {%- if tplgroupmembers.system %}
    - system: {{ tplgroupmembers.system }}
    {%- endif %}
    {%- if tplgroupmembers.change == 'add' %}
    - addusers: {{ tplgroupmembers.users }}
    {%- elif tplgroupmembers.change == 'del' %}
    - delusers: {{ tplgroupmembers.users }}
    {%- else %}
    - members: {{ tplgroupmembers.users }}
    {%- endif %}

{%- endif %}

  3. В файле состояний clean.sls (удаление группы) измените ID состояний:

    # -*- coding: utf-8 -*-
# vim: ft=sls

{#- Get the `tplroot` from `tpldir` #}
{%- set tplroot = tpldir.split('/')[0] %}
{%- from tplroot ~ "/map.jinja" import mapdata as tplgroupmembers with context %}

{%- if tplgroupmembers.group_name %}

my-group-members-group-absent:
  group.absent:
    - name: {{ tplgroupmembers.group_name }}

{%- endif %}

  4. Измените файл map.jinja(словарь со значениями по умолчанию). Например, добавьте в группу sudo некоторых пользователей, для этого:

    1. Измените имя ключа для словаря в хранилище Pillar, используемого для динамического переопределения значений по умолчанию.

    2. Измените значение group_name на sudo.

    3. Измените значение change на add (добавить в группу).

    4. Измените значение users, указав список пользователей.

      {% set mapdata = salt['grains.filter_by']({
    'default': {
        'group_name': 'sudo',
        'gid': '',
        'system': false,
        'change': '',
        'users': [
            'user1',
            'user2',
        ],
    },
}, merge=salt['pillar.get']('my-group-members:lookup'), base='default') %}
После того как формула будет написана, следуйте инструкциям по работе с формулой в разделе «Работа с формулами».

Интеграции

Раздел содержит описание:

Интеграция бэкенда продукта с модулем координации (SaltStack) через брокер сообщений Kafka

На Рис. 1 представлена схема интеграции бэкенда продукта с модулем координации (SaltStack) через брокер сообщений Kafka.

kafka integration
Рис. 1. Интеграция бэкенда продукта с модулем координации (SaltStack)

В рамках интеграции c модулем координации бэкенд продукта обеспечивает:

  • передачу данных со всех серверов управления (masters) в бэкенд продукта с помощью подписки на топик Apache Kafka;

    В брокере сообщений Kafka создается топик — логическая единица организации данных. Каждый топик представляет собой некоторое количество записей, которые называются сообщениями. Производитель, Kafka returner — модуль сервера управления (master), отправляет результаты выполнения команд и состояний, полученные от агентов (minions), в топик для дальнейшей обработки, а потребитель, бэкенд продукта, читает сообщения из него.

  • распределение запросов на установку ПО между серверами управления (masters).

    При запросе на установку ПО на агенте (minion) бэкенд продукта отправляет HTTP-запрос, содержащий идентификатор агента (minion), на соответствующий сервер управления (master). Чтобы корректно определить сервер управления (master), бэкенд продукта анализирует следующие сообщения о событиях SaltStack, полученные через брокер сообщений Kafka:

    • minion_ping — указывает на то, что агент (minion) только что отправил ping-запрос на сервер управления (master);

    • minion_start — указывает на то, что агент (minion) только что запустился;

    • /minion/refresh/<minion-id> — указывает на то, что была выполнена операция обновления данных на агенте (minion) с указанным идентификатором, который определяет Kafka returner при обработке сообщений.

Перед тем как настроить интеграцию необходимо:

  1. Установить Apache Kafka, следуя инструкциям в официальной документации.

  2. Создать отдельный топик (например, salt-topic), следуя инструкции в официальной документации. Для топика рекомендуется задать параметры:

    1. retention — время, в течение которого сообщения будут храниться в топике до момента удаления;

    2. partitions — способ физического разделения данных в топике на несколько частей. Эти параметры могут быть настроены в зависимости от требований к производительности и надежности системы.

Настройка интеграции выполняется в несколько шагов при установке продукта отдельно для каждого сервера управления (master) и агента (minion). Подробное описание каждого шага содержится в руководстве по установке.

Последовательность шагов:

  1. При конфигурировании сервера управления (master) выполните настройку отправки событий в топик Apache Kafka (см. раздел «Настройка конфигурации отправки событий в Apache Kafka» документа «Руководство по установке»).

  2. После того как будут заданы настройки сервера управления (master), выполните настройку Kafka returner (см. раздел «Настройка Kafka returner» документа «Руководство по установке»).

  3. При конфигурировании агента (minion) задайте интервал времени (ping_interval) между отправкой ping-запросов от агента (minion) на сервер управления (master) (см. раздел «Настройка конфигурации агента (minion)» документа «Руководство по установке»).

  4. При конфигурировании бэкенда в файле application.properties задайте:

    • параметры подключения к топику Kafka (см. раздел см. «Предварительная конфигурация бэкенда. Параметры настройки интеграции с Apache Kafka» документа «Руководство по установке»);

    • одинаковые порт, на котором будет запущен API-интерфейс, логин и пароль для подключения к серверу управления (master) (см. раздел см. «Предварительная конфигурация бэкенда. Параметры настройки интеграции с S3-совместимым хранилищем» документа «Руководство по установке»).

Интеграция с S3-совместимым хранилищем

На Рис. 1 представлена схема интеграции с S3-совместимым хранилищем.

s3 integration
Рис. 2. Интеграция с S3-совместимым хранилищем

Интеграция с S3-совместимым хранилищем обеспечивает:

  • хранение файлов формул и файлов Pillar модуля координации (SaltStack);

  • хранение мультимедиа-контента, который используется для отображения в пользовательском интерфейсе «Магазин приложений».

Перед тем как настроить интеграцию необходимо:

  1. Cоздать техническую учетную запись для подключения к хранилищу.

  2. Создать бакеты:

    • salt-bucket — для хранения формул модуля координации (SaltStack);

    • pillar-bucket — для хранения данных хранилища Pillar модуля координации (SaltStack);

    • icons-bucket — для хранения иконок;

    • images-bucket — для хранения изображений и скриншотов;

    • others-bucket — для хранения прочего мультимедиа-контента;

    • script-bucket — для исполняемых файлов (скриптов), предназначенных для установки агентов (minions) на устройства.

Настройка интеграции выполняется в несколько шагов при установке продукта отдельно для каждого сервера управления (master). Подробное описание каждого шага содержится в руководстве по установке.

Последовательность шагов для настройки хранения файлов формул и файлов Pillar модуля координации (SaltStack):

  1. При конфигурировании сервера управления (master) выполните настройку подключения сервера управления (master) к бакетам salt-bucket и pillar-bucket (см. раздел «Настройка подключения к S3-совместимому хранилищу» документа «Руководство по установке»).

(Опционально) загрузите пользовательские формулы в бакет salt-bucket, который вы подключили к

серверу управления (master), используя API-метод importFormulas.

+ NOTE: Описание API-метода importFormulas а также подробную информацию о создании и использовании формул см. в разделе «Работа с формулами».

Для загрузки мультимедиа-контента в бакеты icons-bucket, images-bucket и others-bucket используются соответствующие API-методы (см. раздел «Управление мультимедиа-контентом» документа «Описание API»).

Интеграция бэкенда продукта с LDAP-сервером

Интеграция бэкенда продукта с LDAP-сервером позволяет организовать централизованное управление учетными данными пользователей и ресурсами.

Чтобы включить интеграцию, выполните шаги:

  1. Задайте настройки подключения к LDAP-серверу в конфигурационном файле application.properties.

  2. Выполните настройку импорта данных пользователей в пользовательском интерфейсе администратора.

  3. Выполните настройку импорта данных устройств в пользовательском интерфейсе администратора.

Настройка подключения к LDAP-серверу

При установке или последующей настройке продукта в конфигурационном файле application.properties каталога /opt/inno-lcm-core задайте настройки подключения к LDAP-серверу (см. раздел «Предварительная конфигурация бэкенда» документа «Руководство по установке».

Пример:

lcm.inventory.ldap.datasource[0].name=lcm-1583.terra.inno.tech
lcm.inventory.ldap.datasource[0].host=10.6.32.204
lcm.inventory.ldap.datasource[0].port=636
lcm.inventory.ldap.datasource[0].username=Administrator@lcm-1583.terra.inno.tech
lcm.inventory.ldap.datasource[0].password=Welkom123
lcm.inventory.ldap.datasource[0].ssl=true
lcm.inventory.ldap.datasource[0].ssl-certificate=/opt/inno-lcm-core/samba_cert.pem
lcm.inventory.ldap.datasource[0].connect-timeout-millis=10000
lcm.inventory.ldap.datasource[0].response-timeout=10000
lcm.inventory.ldap.datasource[0].abandon-on-timeout=true
lcm.inventory.ldap.datasource[0].allow-concurrent-socket-factory-use=true
lcm.inventory.ldap.search-page-size=200

Где:

Наименование Описание Значение по умолчанию Пример значения

lcm.inventory.ldap.datasource[0].name

Название источника данных (например, имя домена)

lcm-1583.terra.inno.tech

lcm.inventory.ldap.datasource[0].host

IP-адрес или сетевое имя контроллера домена

10.6.32.204

lcm.inventory.ldap.datasource[0].port

Порт для соединения по протоколу LDAP. Опциональный параметр

389; для LDAP over SSL обычно используется порт 636

636

lcm.inventory.ldap.datasource[0].username

Имя пользователя для подключения к домену LDAP-сервера.

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

  • <имя_пользователя>@<имя домена>, например, ivanov@INNO;

  • пользователь в формате LDAP, например, CN=ivanov,CN=Users,DC=inno,DC=local

Administrator@lcm-1583.terra.inno.tech

lcm.inventory.ldap.datasource[0].password

Пароль пользователя для подключения к домену LDAP-сервера

Welkom123

lcm.inventory.ldap.datasource[0].ssl

Параметр, отвечающий за соединение по протоколу LDAP over SSL (LDAPS).

Возможные значения:

  • false — соответствует выключенному протоколу LDAPS, используется обычный LDAP;

  • true — соответствует включенному протоколу LDAPS, требует наличия файла с сертификатом для SSL-соединения (задается отдельным параметром);

  • trust-all — соответствует включенному протоколу LDAPS, принимает любые сертификаты без подтверждения.

Опциональный параметр

false

true

lcm.inventory.ldap.datasource[0].ssl-certificate

Относительный или абсолютный путь к файлу с сертификатом для подключения через LDAPS. Опциональный параметр

См. раздел «Получение сертификата SSL для синхронизации пользователей по протоколу LDAPS» документа «Руководство по установке»

certificate.pem

/opt/inno-lcm-core/samba_cert.pem

lcm.inventory.ldap.datasource[0].connect-timeout-millis

Максимальная длительность подключения к LDAP-серверу в миллисекундах. Значение 0 означает бесконечное ожидание. Опциональный параметр

10000

10000

lcm.inventory.ldap.datasource[0].response-timeout

Максимальная длительность выполнения запроса к LDAP-серверу в миллисекундах. Значение 0 означает бесконечное ожидание. Опциональный параметр

10000

10000

lcm.inventory.ldap.datasource[0].abandon-on-timeout

Параметр, который отвечает за освобождение соединения в случае превышения максимальной длительности ожидания запроса. Возможные значения: true и false. Опциональный параметр

true

true

lcm.inventory.ldap.datasource[0].allow-concurrent-socket-factory-use

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

true

true

lcm.inventory.ldap.search-page-size

Максимальное количество пользователей, которое будет возвращаться в ответ на один запрос синхронизации с LDAP-сервером. Чем больше значение, тем больше данных LDAP-серверу необходимо обработать в рамках одного запроса. Чем меньше значение, тем дольше будет выполняться синхронизация

200

200

Нумерация массива lcm.inventory.ldap.datasource начинается с 0.

Параметры подключения к домену №2 аналогичны параметрам домена №1.

Пример:

lcm.inventory.ldap.datasource[1].name=lcm-1584.terra.inno.tech
lcm.inventory.ldap.datasource[1].host=10.6.32.205
lcm.inventory.ldap.datasource[1].port=636
lcm.inventory.ldap.datasource[1].username=Administrator@lcm-1583.terra.inno.tech
lcm.inventory.ldap.datasource[1].password=Welkom123
lcm.inventory.ldap.datasource[1].ssl=true
lcm.inventory.ldap.datasource[1].ssl-certificate=/opt/inno-lcm-core/samba_cert.pem
lcm.inventory.ldap.datasource[1].connect-timeout-millis=10000
lcm.inventory.ldap.datasource[1].response-timeout=10000
lcm.inventory.ldap.datasource[1].abandon-on-timeout=true
lcm.inventory.ldap.datasource[1].allow-concurrent-socket-factory-use=true

Настройка импорта учетных данных пользователей c сервера LDAP в БД продукта

Параметры импорта пользователей с сервера LDAP в БД продукта задаются посредством графического интерфейса администратора. Администратор настраивает отдельно для каждого LDAP-сервера (источника):

  • включение/выключение импорта;

  • расписание синхронизации;

  • набор папок внутри LDAP-структуры;

  • фильтры для извлечения пользователей.

Подробную информацию см. в разделе «Инвентаризация пользователей» в документе «Руководство администратора»).
Импортируемые данные пользователей

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

Параметр на LDAP-сервере Параметр в БД Описание

objectGUID

users.id

Уникальный идентификатор пользователя

sAMAccountName

users.login

Имя пользователя для входа в систему (Логин)

userAccountControl

true

Указывает, что учетная запись пользователя выключена

userPrincipalName

users.domain_full_name

Полное доменное имя пользователя (например, ivanov@inno.tech или petrov@samara.vtb.ru)

userPrincipalName (подстрока)

users.domain

Имя домена в короткой форме записи (например, inno.tech или samara.vtb.ru)

mail

users.email

Адрес электронной почты

cn

users.common_name

Общее имя пользователя

name

users.first_name

Короткое имя пользователя

givenName

users.given_name

Имя пользователя

sn

users.last_name

Фамилия пользователя

displayName

users.display_name

Отображаемое имя пользователя

title

users.title

Должность пользователя

department

users.department

Отдел, в котором работает пользователь

company

users.company

Подразделение, в котором работает пользователь

memberOf

user_groups.group_name

Группы пользователя, связь один к многим

Настройка импорта данных устройств c сервера LDAP в БД продукта

Параметры импорта данных устройств с сервера LDAP в БД продукта задаются посредством графического интерфейса администратора. Администратор настраивает отдельно для каждого LDAP-сервера (источника):

  • включение/выключение импорта;

  • расписание синхронизации.

Подробную информацию см. в разделе «Инвентаризация устройств» в документе «Руководство администратора»).
Импортируемые данные устройств

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

Параметр на LDAP-сервере Параметр в БД Описание

distinguishedName

ldap_dn

Уникальное имя (DN) устройства

cn

node_name

Общее имя устройства

operatingSystem

os_fullname

Операционная система

objectSid

object_sid

Идентификатор безопасности

Работа с коллекциями устройств

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

Коллекция устройств — это множество устройств, которое формируется в результате фильтрации всех устройств по атрибутам самих устройств и атрибутам пользователей, ассоциированных с ними.

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

Основные операции по работе с пользователями, устройствами и коллекциями выполняются в графическом интерфейсе администратора. Подробнее см. раздел «Основные сценарии использования» в документе «Руководство администратора»).

Сбор данных по аппаратной конфигурации устройств

В рамках инвентаризации в БД продукта импортируются следующие технические характеристики устройств из модуля координации:

  • актуальные данные по аппаратной конфигурации устройства;

  • актуальные данные системного ПО устройства;

  • список фактически развернутого прикладного и системного ПО на устройстве.

Данные поступают от агентов (minions) с помощью механизма Grains на сервер управления (master) согласно заданному расписанию.

Сервер управления (master) публикует их в виде события в канале REST endpoint Events, который прослушивается бэкендом продукта. Каждое из таких событий содержит технические характеристики по одному из агентов (minions), которые актуализируются в БД:

Параметр устройства из ответа модуля координации Параметр в БД Описание

id

machines.minion_id

Идентификатор агента (minion)

nodename

machines.node_name

Короткое имя устройства (NetBIOS name)

fqdn

machines.fqdn

Полное доменное имя устройства

fqdn_ip4

machines.domain_ip

Набор доменных адресов IPv4

domain

machines.domain

Имя домена

num_cpus

machines.cpu_num

Количество ядер процессора

cpu_model

machines.cpu_model

Модель процессора

cpuarch

machines.cpu_arc

Архитектура процессора

mem_total

machines.ram

Объем ОЗУ

swap_total

machines.swap

Общий физический размер свопинга

hwaddr_interfaces

machine_networks.mac

Физические адреса сетевого оборудования (MAC)

ip4_gw

machines.ip4_gw

Шлюз Ipv4

ip4_interfaces

machine_networks.ipv4_list

Сетевые интерфейсы IPv4

ip6_interfaces

machine_networks.ipv6_list

Сетевые интерфейсы IPv6

ssds

machine_disks

Диски SSD

disks

machines.machine_disks

Диски HDD

serialnumber

machines.serial_number

Серийный номер устройства

kernel

machines.kernel

Ядро ОС

kernelrelease

machines.kernel_release

Релиз ядра ОС

lsb_distrib_codename

machines.distrib_codename

Код дистрибутива ОС

lsb_distrib_description

machines.os_description

Описание версии ОС

oscodename

machines.os_codename

Код версии ОС

osarch

machines.cpu_arc

Архитектура ОС

osfullname

machines.os_fullname

Полное наименование ОС

osmajorrelease

machines.os_major_release

Мажорная версия релиза ОС

osrelease

machines.os_release

Версия релиза ОС

saltversion

machines.salt_version

Версия модуля координации на агенте (minion)

master

machines.salt_master

Имя сервера управления (master)

pythonversion

machines.python_version

Версия Python для модуля координации на агенте (minion)

_stamp

machines.updated_at

Дата и время актуализации характеристик

Настройка расписания синхронизации агентов (minions) с сервером управления (master)

Расписание синхронизации агентов (minions) с сервером управления (master) с настройками по умолчанию задается в БД для всей системы при установке продукта.

Настройки определяют:

  • операции, для которых выполняется синхронизация:

    • инвентаризации устройств (highstate);

    • синхронизации параметров Grains (grains);

    • применения назначенных конфигураций на устройствах (grainsSync);

    • синхронизации хранилища Pillar (refreshPillar);

  • интервал в секундах, через который выполняется операция (seconds);

  • интервал в секундах, на который может быть случайная задержка перед выполнением операции (splay).

Значения по умолчанию:

{
  "highstate": {
    "seconds": 84400,
    "splay": 14400
  },
  "grains": {
    "seconds": 14400,
    "splay": 2400
  },
  "grainsSync": {
    "seconds": 84400,
    "splay": 14400
  },
  "refreshPillar": {
    "seconds": 14400,
    "splay": 2400
  }
}

Чтобы просмотреть текущие настройки или изменить их, используйте соответствующие API-методы (см. раздел «API логического модуля «Инвентаризация»» документа «Описание API»).

Таблицы базы данных

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

Таблица users

Содержит информацию о системных пользователях.

Параметр Описание Тип данных Ограничение Not null Возможные значения

id

Уникальный идентификатор пользователя. Первичный ключ

uuid

Не может быть пустым

8c69bf10-5231-35be-a7be-b27938a4127b

login

Имя пользователя для входа в систему (Логин)

text

Не может быть пустым

login67163

domain

Имя домена в короткой форме записи

text

Не может быть пустым

vlev.local

full_domain_name

Полное доменное имя пользователя в формате <логин_пользователя@имя_домена>

text

Не может быть пустым

login67163@vlev.local

email

Адрес электронной почты пользователя

text

Может оставаться пустым

email79740@inno.tech

first_name

Имя пользователя

text

Может оставаться пустым

Иван

last_name

Фамилия пользователя

text

Может оставаться пустым

Иванов

common_name

Общее имя пользователя

text

Может оставаться пустым

Иван Иванов

display_name

Отображаемое имя пользователя

text

Может оставаться пустым

Иван Иванов

title

Должность пользователя

text

Может оставаться пустым

технический писатель

department

Отдел, в котором работает пользователь

text

Может оставаться пустым

отдел технической документации

company

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

text

Может оставаться пустым

ООО "ТехДокс"

disabled

Указывает, является ли пользователь активным или нет

bool

Не может быть пустым

true

raw_groups

Группы, в которых состоит пользователь

text

Может оставаться пустым

CN=Users,DC=vlev

created_at

Дата и время создания записи

timestamp with time zone

Не может быть пустым

2023-09-1807:46:41.019274+00

updated_at

Дата и время обновления записи

timestamp with time zone

Не может быть пустым

2023-09-1808:27:54.048487+00

Таблица machines

Содержит информацию об устройствах.

Параметр Описание Тип данных Ограничение Not null Возможные значения

minion_id

Идентификатор агента (minion). Значение по умолчанию обычно совпадает с полным доменным именем АРМ из поля fqdn. Первичный ключ

text

Не может быть пустым

lcm-salt-minion-01-u

node_name

Имя устройства

text

Не может быть пустым

lcm-salt-minion-01-u

fqdn

Полное доменное имя устройства

text

Не может быть пустым

lcm-salt-minion-01-u

domain

Имя домена

text

Может оставаться пустым

vlev.local

domain_ip

Набор доменных адресов IPv4

text

Не может быть пустым

172.19.0.3

ip4_gw

Шлюз Ipv4

text

Может оставаться пустым

172.19.0.1

cpu_model

Модель процессора

text

Не может быть пустым

11thGenIntel®Core™i5-1135G7@2.40GHz

cpu_arc

Архитектура процессора

text

Не может быть пустым

x86_64

cpu_num

Количество ядер процессора

int

Не может быть пустым

8

ram

Объем ОЗУ в мегабайтах

int

Не может быть пустым

31940

swap

Общий физический размер свопинга в мегабайтах

int

Не может быть пустым

8192

serial_number

Серийный номер устройства

text

Может оставаться пустым

PF2SAAH7

kernel

Ядро ОС

text

Не может быть пустым

Linux

kernel_release

Релиз ядра ОС

text

Не может быть пустым

5.10.16.3-microsoft-standard-WSL2

os_codename

Код версии ОС

text

Не может быть пустым

jammy

os_fullname

Полное наименование ОС

text

Не может быть пустым

Ubuntu

os_description

Описание версии ОС

text

Не может быть пустым

jammy

distrib_codename

Код дистрибутива ОС

text

Не может быть пустым

Ubuntu 22.04.3 LTS

os_arch

Архитектура ОС

text

Не может быть пустым

amd64

os_major_release

Мажорная версия релиза ОС

text

Не может быть пустым

22

os_release

Версия релиза

text

Не может быть пустым

22.04

salt_master

Имя сервера управления (master)

text

Не может быть пустым

lcm-salt-master

salt_version

Версия SaltStack на агенте (minion)

text

Не может быть пустым

3005.1

python_version

Версия Python для SaltStack на агенте (minion)

text

Не может быть пустым

3.9.16.final.0

bios_uefi

Указывает, включена ли опция UEFI в BIOS

bool

Может оставаться пустым

bios_version

Версия BIOS

text

Может оставаться пустым

F8CN53WW(V2.16)

bios_vendor_name

Имя производителя BIOS

text

Может оставаться пустым

LENOVO

bios_uuid

Идентификатор BIOS

text

Может оставаться пустым

9d751d07-f736-11eb-810c-7c8ae191c2ee

bios_release_date

Дата выпуска BIOS

text

Может оставаться пустым

11/12/2020

created_at

Дата и время создания записи

timestamp with time zone

Не может быть пустым

2023-09-18 10:13:31.548795+00

updated_at

Дата и время обновления записи

timestamp with time zone

Не может быть пустым

2023-09-18 10:15:48.519831+00

Таблица machine_networks

Содержит информацию о сетях устройств.

Параметр Описание Тип данных Ограничение Not null Возможные значения

minion_id

Идентификатор агента (minion). Соответствует полю minion_id таблицы machines

text

Не может быть пустым

lcm-salt-minion-01-u

net_name

Имя сети

text

Не может быть пустым

eth0

mac

MAC-адрес

text

Может оставаться пустым

02:42:ac:13:00:03

ipv4_list

Сетевые интерфейсы IPv4 (может быть указано несколько значений через запятую)

text

Может оставаться пустым

172.19.0.3,192.168.0.1

ipv6_list

Сетевые интерфейсы IPv6 (может быть указано несколько значений через запятую)

text

Может оставаться пустым

2a02:f680:1:1100::3d60,2604:a880:800:c1::2ae:d001

updated_at

Дата и время обновления записи

timestamp with time zone

Не может быть пустым

2023-09-1808:39:52.209881+00

Таблица machine_disks

Содержит информацию о дисках.

Параметр Описание Тип данных Ограничение Not null Возможные значения

minion_id

Идентификатор агента (minion). Соответствует полю minion_id таблицы machines

text

Не может быть пустым

lcm-salt-minion-01-u

disk_name

Имя диска

text

Не может быть пустым

sdb

disk_type

Тип диска. Возможные значения: HDD и SSD

text

Может оставаться пустым

HDD

total_space

Общий объем памяти на диске

bigint

Может оставаться пустым

30562713600

used_space

Используемый объем памяти на диске

bigint

Может оставаться пустым

7084609536

free_space

Свободное место на диске

bigint

Может оставаться пустым

21901991936

file_system

Тип файловой системы

text

Может оставаться пустым

ext4

device

Имя устройства

text

Может оставаться пустым

/dev/sda1

updated_at

Дата и время обновления записи

timestamp with time zone

Не может быть пустым

2023-09-18 10:15:48.519831+00

Таблица user_machine_mappings

Содержит данные сопоставления пользователей и устройств.

Параметр Описание Тип данных Ограничение Not null Возможные значения

user_fdn

Полное доменное имя пользователя. Часть составного первичного ключа вместе с параметром machine_fqdn. Может использоваться для связи с таблицей users по полю full_dimain_name

text

Не может быть пустым

login25497@vlev.test

machine_fqdn

Полное доменное имя устройства. Часть составного первичного ключа вместе с параметром user_fdn. Может использоваться для связи с таблицей machines по полю fqdn

text

Не может быть пустым

lcm-salt-minion-01-u

created_at

Дата и время создания записи

timestamp with time zone

Не может быть пустым

2023-09-1808:45:18.000127+00

updated_at

Дата и время обновления записи

timestamp with time zone

Не может быть пустым

2023-09-1808:45:18.000127+00

Таблица groups

Содержит информацию об LDAP-группах.

Параметр Описание Тип данных Ограничение Not null Возможные значения

id

Уникальный идентификатор группы. Первичный ключ

uuid

Не может быть пустым

bfd305c4-fa7d-41c4-b841-1fc37cee06b1

name

Название группы

text

Не может быть пустым

Performance Monitor Users

full_name

Полное название группы. Первичный ключ

text

Не может быть пустым

CN=Performance Monitor Users,CN=Builtin,DC=lcm,DC=terra,DC=inno,DC=tech

object_sid

Идентификатора безопасности

varchar(255)

Не может быть пустым

S-1-5-32-549

description

Описание группы

text

Не может быть пустым

Members of this group can access performance counter data locally and remotely

scope

Область действия:

  • BUILT_IN — группа, встроенная по умолчанию;

  • DOMAIN_LOCAL — локальная группа в домене;

  • GLOBAL — глобальная группа;

  • UNIVERSAL — универсальная группа

varchar(255)

Не может быть пустым

BUILT_IN

type

Тип группы:

  • SECURITY — группа безопасности, которая используется для предоставления доступа к ресурсам;

  • DISTRIBUTION — группа распространения, которая используется для создания групп почтовых рассылок

varchar(255)

Не может быть пустым

SECURITY

created_at

Дата и время создания записи

timestamp with time zone

Не может быть пустым

2023-09-1808:32:15.045738+00

updated_at

Дата и время обновления записи

timestamp with time zone

Не может быть пустым

2023-09-1808:32:15.045738+00

Содержит информацию о ссылках LDAP-групп.

Параметр Описание Тип данных Ограничение Not null Возможные значения

group_full_name

Полное название родительской группы. Соответствует полю full_name таблицы groups

text

Не может быть пустым

CN=Performance Monitor Users,CN=Builtin,DC=lcm,DC=terra,DC=inno,DC=tech

child_full_name

Полное название дочерней группы. Соответствует полю full_name таблицы groups

text

Может быть пустым

CN=Server Operators,CN=Builtin,DC=lcm,DC=terra,DC=inno,DC=tech

updated_at

Дата и время обновления записи

timestamp with time zone

Не может быть пустым

2023-09-1808:32:15.045738+00

Таблица user_groups

Содержит информацию о группах пользователя.

Параметр Описание Тип данных Ограничение Not null Возможные значения

user_id

Уникальный идентификатор пользователя. Часть составного первичного ключа вместе с параметром group_name. Соответствует полю id таблицы users

uuid

Не может быть пустым

efbfbd2b-7417-d089-efbf-bd4befbfbdef

group_name

Наименование группы пользователя. Часть составного первичного ключа вместе с параметром user_id. Соответствует полю full_name таблицы groups

text

Не может быть пустым

CN=Администраторыдомена,CN=Users,DC=vlev,DC=test

updated_at

Дата и время обновления записи

timestamp with time zone

Не может быть пустым

2023-09-1808:32:15.045738+00

Таблица machine_groups

Содержит информацию о группах устройств.

Параметр Описание Тип данных Ограничение Not null Возможные значения

machine_fqdn

Полное доменное имя устройства. Соответствует полю fqdn таблицы machines

text

Не может быть пустым

laptop123.spb.inno.tech

group_full_name

Полное название родительской группы. Соответствует полю full_name таблицы groups

text

Не может быть пустым

CN=Performance Monitor Users,CN=Builtin,DC=lcm,DC=terra,DC=inno,DC=tech

updated_at

Дата и время обновления записи

timestamp with time zone

Не может быть пустым

2023-09-1808:32:15.045738+00

Журналирование

Журналирование — это процесс записи хронологии событий, сообщений или действий программного обеспечения или пользователей, происходящих в системе, в специальные лог-файлы заданного формата. События записываются в режиме, при котором каждая новая запись добавляется в конец файла, а сам файл называется оперативным. При достижении/превышении определенного размера файла содержимое файла автоматически копируется в исторический файл.

Для просмотра лог-файлов рекомендуется использовать специальные утилиты по работе с логами, например, Log File Navigator (lnav).

Для действий, происходящих внутри внешних систем, например, БД, системы хранения контента, веб-сервера, службы каталогов, события в журнал не регистрируются.

Параметры лог-файлов

Оперативный и исторические файлы — это файлы формата JSONL, которые создаются автоматически при установке продукта и хранятся на устройствах, на которых они были сгенерированы, в каталогах:

  • /app/inno-osmax/logs/osmax/core — каталог для хранения файлов бэкенда;

  • /app/inno-osmax/logs/salt/master — каталог для хранения файлов сервера управления (master);

  • /app/inno-osmax/logs/salt/minion — каталог для хранения файлов агентов (minions).

Имена файлов задаются согласно шаблонам:

  • шаблон имени оперативного файла:

    log{-applicationAlias}.log

    Где applicationAlias — название приложения, например: log-osmax-core.log.

  • шаблон имени исторического файла:

    log{-applicationAlias}.log.yyyy-MM-dd.{N}

    Где:

    • N — индекс файла;

    • applicationAlias — название приложения;

    • yyyy-MM-dd — дата ротации файла.

Исторические лог-файлы архивируются и имеют расширение .gz.

По умолчанию предельный размер оперативного файла составляет 10 МБ. Для лог-файлов бэкенда при необходимости можно задать другое значение. Для лог-файлов сервера управления (master) и агентов (minions) значение параметра не конфигурируется.

Описание полей лог-файла

Код поля Описание

ID

Уникальный (в пределах системы и истории её данных) идентификатор события

Timestamp

Время фиксации события приложением/сервисом в формате: 2024-04-26T12:37:23.000Z

Level

Уровень логирования; возможные значения:

  • бэкенд:

    • ALL  —  все сообщения будут записываться в лог-файл;

    • INFO — информационные сообщения о ходе работы приложения/сервиса;

    • WARN — сообщения, содержащие предупреждение о потенциальной проблеме или необычном состоянии, которое не является ошибкой, но требует внимания;

    • DEBUG — сообщения, содержащие отладочную информацию;

    • TRACE — сообщения, содержащие детальную отладочную информацию;

    • ERROR — сообщения об ошибке, которая привела к некритическому сбою;

    • FATAL — сообщения об ошибке, которая привела к критическому сбою;

    • OFF — сообщения в лог-файл записываться не будут;

  • модуль координации (SaltStack):

    • all —  все сообщения будут записываться в лог-файл;

    • warning — сообщения, содержащие предупреждение о потенциальной проблеме или необычном состоянии, которое не является ошибкой, но требует внимания;

    • info — информационные сообщения о ходе работы модуля;

    • profile — профильная информация о производительности модуля координации (SaltStack);

    • debug — сообщения, содержащие отладочную информацию;

    • trace — сообщения, содержащие детальную отладочную информацию;

    • garbage — сообщения, содержащие детальную (чем trace) отладочную информацию;

    • error — сообщения об ошибке, которая привела к некритическому сбою;

    • critical — сообщения об ошибке, которая привела к критическому сбою;

    • quiet — сообщения в лог-файл записываться не будут

AppName

Логическое наименование модуля, инициировавшего событие; возможные значения:

  • osmax-core — бэкенд;

  • salt-master — сервер управления (master);

  • salt-minion — агент (minion)

HostName

Наименование устройства, на котором производится запись событий.

В текущей версии продукта значение HostName будет указываться только для событий бэкенда

Message

Сообщение, описывающее произошедшее событие

Аудит

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

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

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

Для каждого регистрируемого события указываются:

  • тип;

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

  • успешность или не успешность осуществляемых действий;

  • дата и время события;

  • другие данные, достаточные для однозначной интерпретации события (см. раздел «Описание полей лог-файла»).

Для действий, происходящих внутри внешних систем, например, БД, системы хранения контента, веб-сервера, службы каталогов, события аудита не регистрируются.

Параметры лог-файлов

Оперативный и исторические файлы — это файлы формата JSONL, которые создаются автоматически при установке продукта и хранятся в каталоге /app/inno-osmax/audit/osmax/core.

Имена файлов задаются согласно шаблонам:

  • шаблон имени оперативного файла:

    audit{-applicationAlias}.log

    Где applicationAlias — название приложения, например: audit-osmax-core.log.

  • шаблон имени исторического файла:

    audit{-applicationAlias}.log.yyyy-MM-dd.{N}

    Где:

    • N — индекс файла;

    • applicationAlias — название приложения;

    • yyyy-MM-dd — дата ротации файла.

По умолчанию предельный размер оперативного файла аудита составляет 10 МБ. При необходимости можно задать иное значение.

Описание полей лог-файла

Родительский элемент Элемент Описание

$

timestamp

Дата и время генерации события на сервере. Формат: YYYY-MM-DD’T’hh:mm:ss.SSSXXX

$

id

Идентификатор события

$

correlationId

Идентификатор группы событий (например, начало и окончание фоновой процедуры)

Данные о типе событий

$

type

Тип события. Заполняется на русском языке

$

code

Код события

Данные об объекте и операции

$

object.id

Идентификатор бизнес-объекта, над которым выполняется действие, например 765. Если у бизнес-объекта нет идентификатора, указывается символ "-"

$

object.name

Название типа объекта, над которым выполняется действие. Например, "конфигурация". Заполняется на русском языке

Данные о событии, связанные с классом сообщения о событии

$

class

Класс сообщения о событии. Возможные значения:

  • SUCCESS;

  • FAILURE

$

message

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

Описание параметров события передается в поле additionalParams

$

sub

Имя пользователя, например, iivanov@inno.tech

Если событие — это вызов конечной точки (end point), то указываются данные из тикета Kerberos (Principal.simpleName и Principal.realm), в остальных случаях указывается символ "-"

$

ipAddress

IP-адрес пользователя; указывается первое значение из заголовка запроса X-Forwarded-For.

Данные о контексте события

$.context

url

URL-адрес конечной точки, указанный вместе с протоколом и параметрами.

Поле заполняется, только если событие — это вызов конечной точки (end point). В остальных случаях указывается символ "-"

$.context

method

HTTP-метод

Поле заполняется, только если событие — это вызов конечной точки (end point). В остальных случаях указывается символ "-"

Дополнительные параметры

$

additionalParams

Все дополнительные параметры сообщения

$

exception

Информация об ошибке в произвольном формате, если действие завершилось неудачно (success = failure)

Данные для интеграции с системой централизованного мониторинга событий безопасности клиента

$

scmCategory

Возможные значения:

  • ENTRY_EXIT_OPERATIONS — операции входа/выхода в пользовательский интерфейс;

  • ACCOUNT_MANAGEMENT_OPERATIONS — управление учётными записями;

  • PRIVELEGES_MANAGEMENT_OPERATIONS — управление ролями и привилегиями;

  • SYSTEM_ERRORS — системные ошибки/сбои.

В текущей версии продукта используется только значение PRIVELEGES_MANAGEMENT_OPERATIONS для событий ROLES-*.

В остальных случаях указывается значение null

Пример лога:

{
   "timestamp":"2024-05-27T13:52:23.116Z",
   "sequence":32,
   "loggerClassName":"io.github.oshai.kotlinlogging.slf4j.internal.LocationAwareKLogger",
   "loggerName":"AUDIT",
   "level":"INFO",
   "message":"Авторизация в приложении",
   "threadName":"Test worker @coroutine#1",
   "threadId":1,
   "initiator.sub":"null@null",
   "context.method":"-",
   "correlationId":"477fd1da-1710-4485-93d6-71911ca9618f",
   "exception":"Exception message",
   "class":"FAILURE",
   "code":"AUTH-003",
   "type":"Авторизация",
   "context.url":"-",
   "id":"555b9c04-f0ba-4a6a-a219-d426bdfea752",
   "object.id":"-",
   "componentName":"lcm-core",
   "ipAddress":"-",
   "hostName":"avakimov01",
   "processName":"GradleWorkerMain",
   "processId":27492
}

События аудита

События аутентификации

type code object.id message object.name class additionalParams Описание

Аутентификация

AUTH-001

-

Аутентификация в приложении

null

Возможные значения:

  • success;

  • failure (в случае HTTP-ошибки с кодом 401)

сomponentName — компонент продукта, например, lcm-core

Проверка валидности Kerberos-тикета при любом запросе от фронтенда

События авторизации

type code object.id message object.name class additionalParams Описание

Авторизация

AUTH-003

-

Авторизация в сервисном приложении

null

Возможные значения:

  • success;

  • failure (в случае HTTP-ошибки с кодом 403)

сomponentName — компонент продукта, например, lcm-core

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

События управления ролевым доступом

type code object.id message object.name class additionalParams Описание

Создание

ROLES-001

Id роли из ответа

Создание роли

роль

Возможные значения:

  • success;

  • failure (в случае HTTP-ошибок с кодом 4хх или 5xx, кроме 401 и 403)

  • roleName — имя роли; для методов POST и PUT указывается значение из запроса; для методов PUT и DELETE указывается значение из поля name таблицы БД lcm.roles; поиск выполняется по идентификатору, указанному в запросе;

  • roleId — идентификатор роли

Создание роли, которая не привязана к пользователю/группе

Изменение

ROLES-002

Id роли из запроса

Изменение роли

роль

Возможные значения:

  • success;

  • failure (в случае HTTP-ошибок с кодом 4хх или 5xx, кроме 401 и 403)

  • roleName — имя роли; для методов POST и PUT указывается значение из запроса; для методов PUT и DELETE указывается значение из поля name таблицы БД lcm.roles; поиск выполняется по идентификатору, указанному в запросе;

  • roleId — идентификатор роли

Изменение характеристик роли без изменения состава полномочий роли и без изменения привязки к пользователям/группам

Удаление

ROLES-003

Id роли из запроса

Удаление роли

роль

Возможные значения:

  • success;

  • failure (в случае HTTP-ошибок с кодом 4хх или 5xx, кроме 401 и 403)

  • roleName — имя роли; для методов POST и PUT указывается значение из запроса; для методов PUT и DELETE указывается значение из поля name таблицы БД lcm.roles; поиск выполняется по идентификатору, указанному в запросе;

  • roleId — идентификатор роли

Удаление и отвязка роли от пользователей/групп

Изменение

ROLES-004

Id роли из запроса

Изменение списка доступных действий над объектами в рамках роли

роль

Возможные значения:

  • success;

  • failure (в случае HTTP-ошибок с кодом 4хх или 5xx, кроме 401 и 403)

  • roleName — имя роли; для методов POST и PUT указывается значение из запроса; для методов PUT и DELETE указывается значение из поля name таблицы БД lcm.roles; поиск выполняется по идентификатору, указанному в запросе;

  • roleId — идентификатор роли

Изменение полномочий роли. Если роль привязана к пользователю/группе, то у пользователя/группы появятся полномочия в системе

Изменение

ROLES-005

Id роли из запроса

Назначение роли пользователю или группе

роль

Возможные значения:

  • success;

  • failure (в случае HTTP-ошибок с кодом 4хх или 5xx, кроме 401 и 403)

  • userName — имя пользователя;

  • roleName — имя роли; для методов POST и PUT указывается значение из запроса; для методов PUT и DELETE указывается значение из поля name таблицы БД lcm.roles; поиск выполняется по идентификатору, указанному в запросе;

  • roleId — идентификатор роли

Роль привязывается к пользователю/группе. У пользователя/группы через роль появляются полномочия в системе

Изменение

ROLES-006

Id роли из запроса

Отзыв роли у пользователя или группы

роль

Возможные значения:

  • success;

  • failure (в случае HTTP-ошибок с кодом 4хх или 5xx, кроме 401 и 403)

  • userName — имя пользователя;

  • roleName — имя роли; для методов POST и PUT указывается значение из запроса; для методов PUT и DELETE указывается значение из поля name таблицы БД lcm.roles; поиск выполняется по идентификатору, указанному в запросе;

  • roleId — идентификатор роли

Роль отвязывается от пользователя/группы. У пользователя/группы из-за отвязки роли пропадают полномочия в системе

Системные события

type code object.id message object.name class StartTime и EndTime additionalParams Описание

Процедура

OBJ-010

-

Автоматическое сопоставление

null

Возможные значения:

  • succes — в случае успешного выполнения;

  • failure — в случае неуспешного выполнения

По заданному расписанию

trigger — расписание

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

Установка

SOFT-003

-

Установка, обновление, удаление ПО, запуск или остановка служб, настройка ОС в фоновом режиме

null

Возможные значения:

  • succes — в случае успешного выполнения;

  • failure — в случае неуспешного выполнения

Значение, указанное в поле _stamp в сообщении (значение указано в UTC)

  • installation — название отработавшего пакета;

  • minion — имя агента (minion)

Установка, обновление, удаление ПО, запуск или остановка служб, настройка ОС в фоновом режиме. Событие генерируется из сообщения топика Kafka salt-topic

Установка

SOFT-004

-

Установка, обновление, удаление ПО, запуск или остановка служб, настройка ОС в push-режиме

null

Возможные значения:

  • succes — в случае успешного выполнения;

  • failure — в случае неуспешного выполнения

Значение, указанное в поле _stamp в сообщении (значение указано в UTC)

  • installation — название отработавшего пакета;

  • minion — имя агента (minion)

Установка, обновление, удаление ПО, запуск или остановка служб, настройка ОС в push-режиме. Событие генерируется из сообщения топика Kafka salt-topic

Установка

SOFT-005

-

Установка агента на устройство

null

Возможные значения:

  • succes — в случае успешного выполнения;

  • failure — в случае неуспешного выполнения

Значение, указанное в поле _stamp в сообщении (значение указано в UTC)

minion — имя агента (minion)

Установка агента (minion) на устройство. Событие генерируется из сообщения топика Kafka salt-topic

Процедура

OBJ-102

-

Автоматический пересчёт коллекции

null

Возможные значения:

  • succes — в случае успешного выполнения;

  • failure — в случае неуспешного выполнения

По расписанию

trigger — расписание

Автоматический пересчет коллекции устройств. Событие запускается по расписанию. Изменения сохраняются в БД

Интеграция

INTEG-001

-

Cинхронизация данных по пользователям, устройствам, группам c хранилищем

null

Возможные значения:

  • succes — в случае успешного выполнения;

  • failure — в случае неуспешного выполнения

По расписанию

  • trigger — расписание;

  • store — LDAP-сервер

Cинхронизация данных по пользователям, устройствам, группам c данными на LDAP-сервере. Событие запускается по расписанию. Пользователи, устройства, группы сохраняются в БД

События, связанные с действиями администратора в КА

type code object.id message object.name class additionalParams Описание

Действия администратора, связанные с интеграцией

Загрузка

INTEG-004

-

Загрузка формул отдельно от конфигурации

null

Возможные значения:

  • success;

  • failure (в случае HTTP-ошибок с кодом 4хх или 5xx, кроме 401 и 403)

formula — имя файла из запроса

Загрузка формул, в которых описана установка ПО, запуск служб, настройка ОС и т.д., в S3-совместимое хранилище

Загрузка

INTEG-005

-

Загрузка файла в хранилище

файл

Возможные значения:

  • success;

  • failure (в случае HTTP-ошибок с кодом 4хх или 5xx, кроме 401 и 403)

fileName — имя файла (параметр originalFileName из запроса)

Загрузка файла с изображением, которое будет использоваться как обложка для графического интерфейса «Магазин администратора» в S3-совместимое хранилище

Интеграция

INTEG-009

-

Принудительный запуск синхронизации пользователей, устройств, групп c хранилищем

null

Возможные значения:

  • success;

  • failure (в случае HTTP-ошибок с кодом 4хх или 5xx, кроме 401 и 403)

  • trigger — ручной запуск;

  • store — LDAP-сервер

Принудительный запуск синхронизации пользователей, устройств, групп c данными LDAP-сервера. Группы, устройства, пользователи сохраняются в БД

Действия администратора, связанные с инвентаризацией

Редактирование

OBJ-001

-

Редактирование настроек загрузки пользователей из хранилища

null

Возможные значения:

  • success;

  • failure (в случае HTTP-ошибок с кодом 4хх или 5xx, кроме 401 и 403)

  • datasourceName — datasourceName из запроса;

  • action — возможные значения: New, Edit или Delete;

  • store = LDAP-сервер

Изменения настроек загрузки пользователей с сервера LDAP:

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

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

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

Редактирование

OBJ-002

-

Изменение расписания синхронизации всех сущностей

null

Возможные значения:

  • success;

  • failure (в случае HTTP-ошибок с кодом 4хх или 5xx, кроме 401 и 403)

  • datasourceName — datasourceName из запроса;

  • action — возможные значения: New, Edit или Delete;

  • store = LDAP-сервер

Изменение расписания синхронизации всех сущностей с сервера LDAP

Редактирование

OBJ-003

-

Редактирование настроек загрузки устройств

null

Возможные значения:

  • success;

  • failure (в случае HTTP-ошибок с кодом 4хх или 5xx, кроме 401 и 403)

  • datasourceName — datasourceName из запроса;

  • action — возможные значения: New, Edit или Delete;

  • store = LDAP-сервер

Изменение настроек загрузки устройств с сервера LDAP:

  • добавление нового запроса синхронизации устройств для заданного LDAP-сервера;

  • удаление фильтра синхронизации устройств для заданного LDAP-сервера;

  • изменение фильтра синхронизации устройств для заданного LDAP-сервера

Редактирование

OBJ-005

-

Редактирование настроек загрузки групп

null

Возможные значения:

  • success;

  • failure (в случае HTTP-ошибок с кодом 4хх или 5xx, кроме 401 и 403)

  • datasourceName — datasourceName из запроса;

  • action — возможные значения: New, Edit или Delete;

  • store = LDAP-сервер

Изменение настроек загрузки групп с сервера LDAP:

  • cоздание поискового запроса для LDAP-сервера при синхронизации групп;

  • удаление поискового запроса для LDAP-сервера при синхронизации пользователей;

  • изменение поискового запроса для LDAP-сервера при синхронизации групп

Настройка

OBJ-007

-

Включение или отключение автоматического сопоставления пользователей и устройств

null

Возможные значения:

  • success;

  • failure (в случае HTTP-ошибок с кодом 4хх или 5xx, кроме 401 и 403)

turn — возможные значения: on`и `off

Включение или отключение режима автоматического сопоставления пользователей и устройств

Настройка

OBJ-008

-

Изменение параметров автоматического сопоставления

null

Возможные значения:

  • success;

  • failure (в случае HTTP-ошибок с кодом 4хх или 5xx, кроме 401 и 403)

Изменение атрибутов режима автоматического сопоставления пользователей и устройств

Процедура

OBJ-009

-

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

null

Возможные значения:

  • success;

  • failure (в случае HTTP-ошибок с кодом 4хх или 5xx, кроме 401 и 403)

trigger — ручной запуск

Ручной запуск автоматического сопоставления пользователей и устройств

Загрузка

OBJ-011

-

Импорт файла соответствия пользователей и машин

null

Возможные значения:

  • success;

  • failure (в случае HTTP-ошибок с кодом 4хх или 5xx, кроме 401 и 403)

fileName — имя файла, указанное в запросе

Импорт файла соответствия пользователей и устройств

Настройка

OBJ-012

-

Редактирование значений настроек агентов

null

Возможные значения:

  • success;

  • failure (в случае HTTP-ошибок с кодом 4хх или 5xx, кроме 401 и 403)

schedule — параметр scheduleType из запроса

Изменение настроек расписаний для SaltStack и сохранение их в S3-совместимом хранилище

Выгрузка

OBJ-016

-

Экспорт в файл

null

Возможные значения:

  • success;

  • failure (в случае HTTP-ошибок с кодом 4хх или 5xx, кроме 401 и 403)

  • object — имя ресурса; в зависимости от конечной точки (end point) может принимать одно из значений:

    • users;

    • machines;

    • collections;

    • groups;

  • format — формат файла (CSV-формат)

Выгрузка данных на устройство пользователя:

  • экспорт данных пользователей по критериям в CSV-формате;

  • экспорт данных устройств по критериям в CSV-формате;

  • экспорт данных коллекций по критериям в CSV-формате;

  • выгрузка отчета по группам в CSV-формате

Действия администратора, связанные с коллекциями

Редактирование

OBJ-101

Идентификатор коллекции. Для методов DELETE и PUT указывается идентификатор из path-параметра. Для метода POST указывается идентификатор из ответа

Редактирование коллекций

коллекция

Возможные значения:

  • success;

  • failure (в случае HTTP-ошибок с кодом 4хх или 5xx, кроме 401 и 403)

collectionName — имя коллекции (для методов POST и PUT указывается значение поля name из тела запроса; для метода DELETE —  из поля name таблицы БД machine_collections; поиск выполняется по значению collectionId)

Операции с коллекциями устройств:

  • создание коллекций устройств;

  • получение информации о коллекции устройств;

  • удаление коллекции устройств

Процедура

OBJ-106

-

Запуск процедуры пересчета коллекции в ручном режиме

null

Возможные значения:

  • success;

  • failure (в случае HTTP-ошибок с кодом 4хх или 5xx, кроме 401 и 403)

  • trigger — ручной запуск (manual);

  • collectionName — имя коллекции; указывается значение поля name таблицы БД lcm.machine_collections; поиск выполняется по параметру collectionId из запроса

Запуск процедуры пересчета коллекции устройств в ручном режиме

Действия администратора, связанные с конфигурациями

Редактирование

OBJ-201

Идентификатор конфигурации. Для методов DELETE и PUT указывается значение из path-параметра. Для метода POST — из ответа

Редактирование конфигураций

конфигурация

Возможные значения:

  • success;

  • failure (в случае HTTP-ошибок с кодом 4хх или 5xx, кроме 401 и 403)

configurationName  — имя конфигурации; для методов POST и PUT указывается значение поля displayName из тела запроса; для метода DELETE — поля display_name таблицы БД configurations; поиск выполняется по параметру configurationId, указанному в запросе

Операции с конфигурациями:

  • создание конфигурации;

  • изменение конфигурации по идентификатору;

  • удаление конфигурации по идентификатору

Редактирование

OBJ-202

Идентификатор версии конфигурации. Для методов DELETE и PUT указывается значение из path-параметра. Для метода POST — из ответа

Редактирование версий конфигурации

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

Возможные значения:

  • success;

  • failure (в случае HTTP-ошибок с кодом 4хх или 5xx, кроме 401 и 403)

  • configurationVersionName  — имя версии конфигурации; для методов POST и PUT указывается значение поля displayName из тела запроса; для метода DELETE — поля display_name таблицы БД configuration_versions; поиск выполняется по параметру versionId, указанному в запросе;

  • configurationId  — идентификатор конфигурации; указывается значение из path-параметра;

  • configurationName — имя конфигурации; указывается значение поля display_name таблицы БД configurations; поиск выполняется по параметру configurationId, указанному в запросе

Операции с версиями конфигураций:

  • создание версии конфигурации;

  • изменение версии конфигурации по идентификатору;

  • удаление версии конфигурации по идентификатору

Редактирование

OBJ-203

Идентификатор пакета конфигурации. Для методов DELETE и PUT указывается значение из path-параметра. Для метода POST — из ответа

Редактирование пакетов конфигурации

пакет конфигурации

Возможные значения:

  • success;

  • failure (в случае HTTP-ошибок с кодом 4хх или 5xx, кроме 401 и 403)

  • relativeConfigurationId — идентификатор родительской конфигурации; указывается значение поля configuration_id таблицы БД configuration_packages;

  • configurationPackageName — имя пакета конфигурации; для методов POST и PUT указывается значение поля displayName из тела запроса; для метода DELETE — из БД: 1) выполняется поиск записи таблицы configuration_packages по параметру packageId из запроса 2) выполняется поиск записи configurations по параметру configuration_packages.configuration_id 3) указывается значение из поля display_name

Операции с пакетами конфигураций:

  • создание пакета конфигураций;

  • обновление пакета конфигураций;

  • удаление пакета конфигураций

Выгрузка

OBJ-204

-

Экспорт в файл

null

Возможные значения:

  • success;

  • failure (в случае HTTP-ошибок с кодом 4хх или 5xx, кроме 401 и 403)

  • reportName — название отчета (configurations);

  • format — формат файла (csv)

Экспорт списка конфигураций

Действия администратора, связанные со связками коллекция-конфигурация

Редактирование

OBJ-211

Идентификатор применения. Для, метода DELETE указывается значение из path-параметра; для метода POST — из ответа

Редактирование применения конфигурации или пакета конфигурации к коллекции

применение конфигурации

Возможные значения:

  • success;

  • failure (в случае HTTP-ошибок с кодом 4хх или 5xx, кроме 401 и 403)

* collectionId — идентификатор коллекции; указывается значение из БД по алгоритму: collectionConfigId → запись collection_configurations → поле collection_id; * collectionName — имя коллекции; поиск значения выполняется в несколько этапов: collectionId (см. выше) → запись machine_collections → поле name; * configurationVersionId  — идентификатор версии конфигурации; указывается значение из БД по алгоритму: collectionConfigId → запись collection_configurations → поле configuration_version_id; для метода POST указывается значение из запроса; * configurationName — имя конфигурации; указывается значение из БД по алгоритму: configurationVersionId см. выше) → запись таблицы configuration_versions → запись таблицы configurations → поле display_name; * configurationVersionName — имя версии конфигурации; указывается значение из БД по алгоритму: configurationVersionId (см. выше) → запись таблицы configuration_versions → поле display_name

Операции с сущностью коллекция-конфигурация:

  • применение конфигурации к коллекции;

  • удаление соответствия конфигурации и коллекции

Установка

OBJ-212

Идентификатор применения. Для метода POST указывается значение из ответа

Запуск/остановка применения конфигурации или пакета конфигурации к коллекции

применение конфигурации

Возможные значения:

  • success;

  • failure (в случае HTTP-ошибок с кодом 4хх или 5xx, кроме 401 и 403)

  • action:

    • start, если выполняется запрос на возобновление применения конфигурации к коллекции;

    • stop, если выполняется запрос на остановку применения конфигурации к коллекции;

  • collectionId — идентификатор коллекции; указывается значение из БД по алгоритму: collectionConfigId → запись collection_configurations → поле collection_id;

  • collectionName — имя коллекции; поиск значения выполняется в несколько этапов: collectionId (см. выше) → запись machine_collections → поле name;

  • configurationVersionId  — идентификатор версии конфигурации; указывается значение из БД по алгоритму: collectionConfigId → запись collection_configurations → поле configuration_version_id; для метода POST указывается значение из запроса;

  • configurationName — имя конфигурации; указывается значение из БД по алгоритму: configurationVersionId см. выше) → запись таблицы configuration_versions → запись таблицы configurations → поле display_name;

  • configurationVersionName — имя версии конфигурации; указывается значение из БД по алгоритму: configurationVersionId (см. выше) → запись таблицы configuration_versions → поле display_name

Операции с сущностью коллекция-конфигурация:

  • возобновление применения конфигурации к коллекции;

  • остановка применения конфигурации к коллекции

Выгрузка

OBJ-213

-

Экспорт в файл

null

Возможные значения:

  • success;

  • failure (в случае HTTP-ошибок с кодом 4хх или 5xx, кроме 401 и 403)

  • reportName — название отчета (collection_configurations);

  • format — формат файла (csv)

Операции с сущностью коллекция-конфигурация:

  • экспорт списка применений конфигураций к коллекциям;

  • получение статусов установки конфигурации по каждой машине из соответствующей коллекции

Действия администратора, связанные с сессиями

Удаление

OBJ-301

-

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

null

Возможные значения:

  • success;

  • failure (в случае HTTP-ошибок с кодом 4хх или 5xx, кроме 401 и 403)

Удаление истории сессий

Выгрузка

OBJ-302

-

Получение инфо о сессиях

null

Возможные значения:

  • success;

  • failure (в случае HTTP-ошибок с кодом 4хх или 5xx, кроме 401 и 403)

  • minion — значение, указанное в запросе в поле minionId;

  • user — имя пользователя; указывается значение из поля full_domain_name таблицы БД lcm.users; поиск выполняется по идентификатору, указанному в запросе;

  • fqdn — значение поля fqdn, указанное в запросе;

Если какое-то поле не указано в запросе, то поле детализации события аудита не заполняется

Операции по получению исторических данных о сессиях пользователей на устройствах

  • получение сессий пользователей на указанном устройстве;

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

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

  • экспорт исторической информации о сессиях

Действия администратора, связанные с настройкой отчётов

Редактирование

OBJ-401

Идентификатор отчёта в БД. Для методов DELETE и PUT указывается значение из path-параметра. Для метода POST — из ответа

Регистрация шаблона отчета

отчет

Возможные значения:

  • success;

  • failure (в случае HTTP-ошибок с кодом 4хх или 5xx, кроме 401 и 403)

reportName — имя отчёта; для методов POST и PUT указывается значение поля name из тела запроса; для метода DELETE указывается значение поля name таблицы БД reports; поиск выполняется по reportId, указанному в запросе

Операции с отчетами:

  • создание отчета на основе SQL-запроса;

  • изменение отчета на основе SQL-запроса;

  • удаление отчета по идентификатору

Выгрузка

OBJ-403

Идентификатор отчёта в БД. Указывается значение поля reportId из запроса

Выгрузка отчета

отчет

Возможные значения:

  • success;

  • failure (в случае HTTP-ошибок с кодом 4хх или 5xx, кроме 401 и 403)

name — имя отчёта; указывается значение поля name таблицы БД lcm.report; поиск выполняется по reportId, указанному в запросе

Исполнение отчета

Действия администратора, связанные с модулями grain, state, execution

Редактирование

MODULES-001

Идентификатор файла (saltFileId). Для метода DELETE указывается значение из path-параметра. Для POST — из ответа

Загрузка модулей grain modules, state modules, execution modules

null

Возможные значения:

  • success;

  • failure (в случае HTTP-ошибок с кодом 4хх или 5xx, кроме 401 и 403)

  • module_file_name — имя файла; для метода POST указывается имя file_name из тела запроса; для метода DELETE указывается значение поля file_name таблицы БД salt_files; поиск выполняется по saltFileId, указанному в запросе;

  • salt_file_status — указывается значение поля status из ответа (содержит информацию об общем статусе загрузки файла в S3-совместимое хранилище)

  • import_result — указывается значение поля import_result из ответа (содержит информацию по записи/удалению для каждого S3-совместимого хранилища)

Операции с пользовательскими файлами SaltStack (grains, states, execution modules):

  • загрузка файла SaltStack;

  • удаление файла SaltStack

Grain, State, Execution modules — это модули SaltStack, представленные в виде файлов python. Они могут быть загружены и удалены из S3-совместимого хранилища и в БД. В БД содержится информация о файле, статус загрузки в S3-совместимое хранилище и статус по каждому хранилищу

Процедура

GRAIN-003

-

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

null

Возможные значения:

  • success;

  • failure (в случае HTTP-ошибок с кодом 4хх или 5xx, кроме 401 и 403)

Получение информации о состоянии агентов (minions) из БД

Действия администратора, связанные с запросом удаленного доступа

Запрос

RA-001

-

Запрос для получения удаленного доступа на устройство по выбранному протоколу

null

Возможные значения:

  • success;

  • failure (в случае HTTP-ошибок с кодом 4хх или 5xx, кроме 401 и 403)

  • minion — значение поля minionId, указанное в запросе;

  • protocol — значение поля protocol, указанное в запросе;

  • user — полное доменное имя пользователя

Запрос для получения удаленного доступа на устройство по выбранному протоколу

События, связанные с действиями пользователя в Магазине приложений

type code object.id message object.name class StartTime и EndTime additionalParams

Описание

Запрос

SOFT-001

Идентификатор заказа, указанный в ответе

Создание заказа на установку или обновление или удаление версии ПО

заказ

Возможные значения:

  • success;

  • failure (в случае HTTP-ошибок с кодом 4хх или 5xx, кроме 401 и 403)

  • configurationName — указывается значение поля display_name таблицы БД lcm.configurations; поиск выполняется по configurationId, указанному в запросе;

  • configurationVersionName-- указывается значение поля display_name таблицы БД lcm.configuration_versions; поиск выполняется по configurationVersionId, указанному в запросе;

  • configurationVersionId — значение поля configurationVersionId, указанное в запросе;

  • softName — указывается значение поля formula_name таблицы БД lcm.configurations; поиск выполняется по configurationId, указанному в запросе;

  • action — значение поля action, указанное в запросе

Рекомендации по сбору и предоставлению информации о проблеме/ошибке

В случае возникновения проблемы/ошибки в работе продукта «Служба управления конфигурациями "Осмакс"» сообщите о ней в службу поддержки по электронному адресу lcm_supp@inno.tech.

В обращении:

  1. Укажите максимально детально, в чем заключается проблема/ошибка и в каких условиях она возникла:

    • какие действия выполнялись перед возникновением проблемы/ошибки;

    • какой результат ожидалось получить;

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

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

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

    Логи для продукта снимаются отдельно:

Сбор логов пользовательского интерфейса

Сбор логов пользовательского интерфейса включает сбор консольных и HAR-логов (логов взаимодействия браузера и сервера во время загрузки веб-страницы) в браузере.

Пример сбора логов для Яндекс Браузера:

  • HAR-логи

  • Консольные логи

  1. Нажмите F12 на клавиатуре, чтобы открыть окно инструментов разработчика.

  2. Перейдите на вкладку Сеть.

  3. Нажмите на кнопку Запись сетевого журнала.

  4. Воспроизведите проблему.

  5. Нажмите на кнопку Остановить запись сетевого журнала.

  6. Нажмите на правую кнопку мыши в сетевой таблице и выберите Сохранить все как HAR с контентом.

  7. Выберите папку для сохранения логов и нажмите на кнопку Сохранить.

HAR-логи будут собраны и сохранены в указанной папке.

  1. Нажмите F12 на клавиатуре, чтобы открыть окно инструментов разработчика.

  2. Перейдите на вкладку Консоль.

  3. Нажмите правой кнопкой мыши на любой строке и выберите в контекстном меню Сохранить страницу как.

  4. Выберите папку для сохранения логов и нажмите на кнопку Сохранить.

Консольные логи будут собраны и сохранены в указанной папке.

Пример сбора логов для Chrome:

  • HAR-логи

  • Консольные логи

  1. Нажмите F12 на клавиатуре, чтобы открыть окно инструментов разработчика.

  2. Перейдите на вкладку Network.

  3. Нажмите на кнопку chrome clear, чтобы очистить сетевой журнал.

  4. Выберите чек-боксы Preserve log и Disable cache.

  5. Воспроизведите проблему.

  6. Нажмите chrome export har, чтобы сохранить HAR-логи.

  7. Выберите папку для сохранения логов и нажмите на кнопку Сохранить.

HAR-логи будут собраны и сохранены в указанной папке.

  1. Нажмите F12 на клавиатуре, чтобы открыть окно инструментов разработчика.

  2. Перейдите на вкладку Console.

  3. Нажмите правой кнопкой мыши в любой области окна и выберите в контекстном меню Save as.

  4. Выберите папку для сохранения логов и нажмите на кнопку Сохранить.

Консольные логи будут собраны и сохранены в указанной папке.

Пример сбора логов для Firefox:

  • HAR-логи

  • Консольные логи

  1. Нажмите F12 на клавиатуре, чтобы открыть окно инструментов разработчика.

  2. Перейдите на вкладку Сеть.

  3. Воспроизведите проблему.

  4. Нажмите на правую кнопку мыши в сетевой таблице после воспроизведения проблемы и выберите Сохранить все как HAR.

  5. Выберите папку для сохранения логов и нажмите на кнопку Сохранить.

HAR-логи будут собраны и сохранены в указанной папке.

  1. Нажмите F12 на клавиатуре, чтобы открыть окно инструментов разработчика.

  2. Перейдите на вкладку Консоль.

  3. Нажмите правой кнопкой мыши на любой строке и выберите в контекстном меню Экспортировать видимые сообщения в и выберите Файл.

  4. Выберите папку для сохранения логов и нажмите на кнопку Сохранить.

Консольные логи будут собраны и сохранены в указанной папке.

Сбор логов серверной части

Информацию о сборе логов серверной части см. в разделе «Журналирование».

Информационно-справочные материалы

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

Cron-выражение формата Quartz

Cron-выражение формата Quartz относится к формату временных интервалов, которые используются в системе планирования задач Quartz. Этот формат представляет собой строку, содержащую шесть или семь полей, разделенных пробелами или табуляцией. В каждом поле задано значение времени или даты, когда задача должна быть выполнена. Поля могут содержать любые разрешенные значения, а также различные комбинации разрешенных специальных символов для этого поля.

Описание полей:

Поле Обязательность заполнения Допустимые значения Допустимые специальные символы

Секунды

Да

0-59

, - * /

Минуты

Да

0-59

, - * /

Часы

Да

0-23

, - * /

День месяца

Да

1-31

, - * ? / L W

Месяц

Да

1-12 или JAN-DEC, где:

  • (1) JAN — январь;

  • (2) FEB — февраль;

  • (3) MAR — март;

  • (4) APR — апрель;

  • (5) MAY — май;

  • (6) JUN — июнь;

  • (7) JUL — июль;

  • (8) AUG — август;

  • (9) SEP — сентябрь;

  • (10) OCT — октябрь;

  • (11) NOV — ноябрь;

  • (12) DEC — декабрь

, - * /

День недели

Да

1-7 или SUN-SAT, где:

  • (1) SUN — воскресенье;

  • (2) MON — понедельник;

  • (3) TUE — вторник;

  • (4) WED — среда;

  • (5) THU — четверг;

  • (6) FRI — пятница;

  • (7) SAT — суббота

, - * ? / L #

Год

Нет

1970-2099

, - * /

Описание специальных символов:

Значение Расшифровка Описание

*

Все значения

Используется для выбора всех значений в поле. Например, если в поле Минуты указано значение *, — это будет означать, что задание должно выполняться каждую минуту

?

Нет специального значения

Используется, когда не важно, какой это должен быть день месяца или день недели. Например, если в поле День месяца указано значение 10, а в поле День недели — ?, — это будет означать, что задание должно выполняться 10-го числа месяца, независимо от того, какой это будет день недели

-

Используются для указания диапазона. Например, если в поле Часы указано значение 10-12, — это будет означать, что задание будет выполняться в 10:00, 11:00 и 12:00 часов

,

Используется для поочередного указания значений. Например, если в поле День недели указано значение MON,WED,FRI, — это будет означать, что задание будет выполняться в понедельник, среду и пятницу

/

Используется для указания приращения. Например, если в поле Секунды указано значение 0/15, — это будет означать, что задание будет выполняться в 0, 15, 30 и 45 секунд; а если указано значение 5/15 — в 5,20,35 и 50 секунд

L

От англ. — last (последний)

Используется для указания значений:

  • в поле День месяца — последнего дня месяца; например, для января — это будет 31 января, а для февраля — 28 февраля в не високосный год;

  • в поле День недели — субботы; однако если значение L используется после другого значения, оно будет означать последние n-дней месяца, например, значение 6L будет означать последнюю пятницу месяца.

Также может использоваться для указания смещения от последнего дня месяца, например, L-3 будет означать третий день до конца месяца.

При использовании символа L важно не указывать списки или диапазоны значений, это может привести к некорректным данным

W

От англ. — weekday (рабочий день)

Используется для указания ближайшего рабочего дня недели (понедельник-пятница) к указанному дню. Например, если в поле День месяца указано значение 15W, — это будет означать, что задание будет выполняться в ближайший рабочий день к 15-му числу месяца. Если 15-е число выпадает на субботу, задание будет запущено в пятницу 14-го числа, а если 15-е число выпадает на воскресенье, то в понедельник 16-го числа. Если 15-е число выпадает на вторник, то задание будет запущено во вторник 15-го числа. Однако, если указано значение 1W для дня месяца, и 1-е число выпадает на субботу, то задание будет запущено в понедельник 3-го числа, так как оно не может пересекать границы дней месяца.

Можно объединить символ W с символом L (LW), чтобы задать значение, которое будет означать последний будний день месяца.

При использовании символа W важно не указывать списки или диапазоны значений, это может привести к некорректным данным

#

Используется для указания n-ного дня месяца. Например, если в поле День недели указано значение 6#3, — это будет означать, что задание будет выполняться в третью пятницу месяца.

Если указано значение #5, а в месяце нет пяти заданных дней недели, то в этом месяце задание выполнено не будет

Примеры выражений:

  • * * * ? * * — задача должна выполняться каждую секунду;

  • 0 * * ? * * — задача должна выполняться каждую минуту;

  • 0 */2 * ? * * — задача должна выполняться каждую четную минуту;

  • 0 0 12 ? * 5#3 — задача должна выполняться каждый месяц в третий четверг месяца с 00:00 до 12:00.

Больше примеров вы можете найти, перейдя по ссылке.

Глоссарий

Basic Input/Output System (BIOS)

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

Certificate Revocation List (CRL)

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

Deb-пакет (Debian package)

Формат упаковки программного обеспечения для операционной системы Debian и ее производных, таких как Ubuntu. Deb-пакет содержит программу или библиотеку, а также информацию о зависимостях и конфигурации. Он может быть установлен с помощью менеджера пакетов, например, apt-get или dpkg. Deb-пакеты облегчают установку и обновление программного обеспечения в системе, а также позволяют управлять зависимостями между пакетами.

Har-логи (HTTP Archive logs)

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

Java Runtime Environment (JRE)

Программное обеспечение, необходимое для запуска Java-приложений на компьютере. Оно содержит в себе виртуальную машину Java (JVM), классы Java API и другие необходимые библиотеки. JRE позволяет пользователям запускать Java-приложения без необходимости установки полного JDK (Java Development Kit).

Kafka returner

Модуль сервера управления (master), который позволяет отправлять результаты выполнения команд и состояний, полученные от агентов (minions), в топик Apache Kafka для дальнейшей обработки или хранения.

Network Security Services (NSS)

Набор библиотек, предназначенных для разработки защищённых кросс-платформенных клиентских и серверных приложений. Приложения, построенные при помощи NSS, могут использовать и поддерживать SSLv3, TLS и многие другие стандарты безопасности.

Network Security Services Database (NSSDB)

База данных, используемая для хранения сертификатов и ключей шифрования в системах, использующих библиотеку Network Security Services (NSS).

Privacy Enhanced Mail (PEM)

Формат кодирования данных, который используется для хранения и передачи сертификатов, закрытых ключей, а также других конфиденциальных данных в виде текста. Формат PEM был разработан для безопасной передачи электронной почты, но сейчас широко используется в SSL/TLS-сертификатах и других системах безопасности.

Simple Storage Service (S3)

Cервис хранения данных в облаке, предоставляемый Amazon Web Services (AWS). Он позволяет хранить и извлекать любой объем данных из любой части мира. S3 используется для хранения статических файлов, таких как изображения, видео, аудио, документы и т.д. Этот сервис также предоставляет возможность управления доступом к данным и автоматического резервного копирования данных. S3 является одним из самых популярных сервисов AWS и широко используется в различных приложениях и сервисах.

Unified Extensible Firmware Interface (UEFI)

Интерфейс между операционной системой и микропрограммами, управляющими низкоуровневыми функциями оборудования, его основное предназначение: корректно инициализировать оборудование при включении системы и передать управление загрузчику или непосредственно ядру операционной системы. EFI — технология, предназначенная для замены BIOS которая обеспечивает более быструю загрузку компьютера, улучшенную безопасность и более простую настройку системы. Она также позволяет использовать жесткие диски большого объема и поддерживает новые технологии, такие как Secure Boot, которая обеспечивает защиту от вредоносных программ.

Автоматизированное рабочее место (АРМ)

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

Операционная система (ОС)

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

Программное обеспечение (ПО)

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

Сокращения

AD

Active Directory
CRL

Certificate Revocation List
BIOS

Basic Input/Output System
JRE

Java Runtime Environment
NSS

Network Security Services
NSSDB

Network Security Services Database
PEM

Privacy Enhanced Mail
S3

Simple Storage Service
UEFI

Unified Extensible Firmware Interface
АРМ

Автоматизированное рабочее место
ОС

Операционная система
ПО

Программное обеспечение