Обмен настроек - astra-settings-exchange#

Архитектура#

О механизме#

astra-settings-exchange — обмен настроек Астры.

Для обмена может использоваться файл (файл-архив), в котором хранятся настройки.

Примечание

Обмен через сеть или другие сетевые IPC не подразумевается.

Важно

Так как в процедуру импорта и экспорта настроек, включён процесс чтения и изменения текущих настроек системы, то в astra-settings-exchange есть отдельная возможность чтения и изменения текущих настроек системы.

astra-settings-exchange поддерживает работу через консоль, с доступными утилитами можно ознакомиться в CLI (консольные утилиты) для astra-settings-exchange.

Модуль#

Модуль astra-settings-exchange — плагин для списка настроек, в котором хранятся правила чтения/записи настроек в файл(ах) и правила на получение/изменение текущих настроек системы.

В модуле есть список настроек, у каждой настройки есть своё внутреннее имя (OptionName).

Внутреннее имя используется для идентификации настроек в модуле.

С форматом внутреннего имени можно ознакомится в разделе «Название настроек (опций)».

Для создания модулей, рекомендуется ознакомиться на странице «Создание модулей настроек в astra-settings-exchange».

Название настроек (опций)#

Название настройки (опции) состоит из:

moduleName - название модуля. Необязательная часть, разделяется от других частей символом двоеточия (:);
groups - название пути группы, для разделения имён групп, используется слэш (/), например group1/group2/. Необязательная часть;
baseName - базовое название настройки (опции). Обязательная часть, не должна быть пустой.

Примеры имён:

- "moduleName:group1/group2/baseName";
- "moduleName:group/baseName";
- "moduleName:baseName";
- "baseName".

Файл для настроек#

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

Примечание

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

Для объединения настроек можно воспользоваться группировкой файлов.

Примечание

Файлы настроек группируются по папкам, группировка происходит по указанной группе у модуля настройки.

Название группы поддерживает символ /, для разделения настроек по вложенным папкам.

astra-settings-exchange может работать напрямую папкой, вместо файла-архива, чтобы не тратить ресурсы на компрессию и распаковку файл-архива.

Процедура импорта настроек#

Процедура импорта настроек состоит из процесса загрузки (load) настроек из файла-архива и процесса изменения (set) текущих настроек системы.

Каждый модуль читает свои настройки и производит изменение текущих настроек системы.

Процедура экспорта настроек#

Процедура экспорта настроек состоит из процесса получения (get) текущих настроек системы и процесса сохранения (save) настроек в файл-архив.

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

Как работает чтение/запись файлов в модулях#

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

Файлы из временной директории размещаются в файле-архиве, по группам модулей.

Создание модулей настроек в astra-settings-exchange#

Базовые примеры#

Базовые примеры доступны по ссылкам:

Типы модулей#

Есть два типа модулей в astra-settings-exchange:

Library - модуль в виде С++ библиотеки с использованием функционала фреймворка Qt;
Native (начиная c astra-settings-exchange_1.2.0) - модуль может быть написан на любых языках, для обмена информацией используется stdout и stderr и аргументы запуска процессов.

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

Название	Library	Native
Создание собственного дескриптора файлов	+	-
Поддержка вариативных типов значений с помощью QVariant	+	-
Использование общих действий PolicyKit	+	-

Информация о модуле#

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

Информация о модулях - обязательная часть, при создании любого модуля, вне зависимости от типа модуля.

Файл информации о модуле#

Для того, чтобы astra-settings-exchange видел модуль, необходимо создать файл информации о модуле, например как файле ase_library_module_template.ini (Базовый пример 1):

[General]
ModuleName=ase_library_module_template
ModuleType=Library
Version=1.0
Group=ase_templates

Параметр ModuleType не обязателен, если не задавать параметр ModuleType, то его значение по умолчанию будет эквивалентно типу модуля в виде библиотеки, то есть значению Library.

Зависимости модулей#

Если ваш модуль завит от другого(их) модуля(ей) astra-settings-exchange, то достаточно указать в файле .ini, поле Depends.

Примечание

Если нужно указать несколько зависимых модулей, то достаточно разделить названия модулей символом точки с запятой (;):

[General]
ModuleName=ase_library_module_template
ModuleType=Library
Version=1.0
Group=ase_templates
Depends=test1;test2;test3

В данном примере: модули test1, test2, test3 будут загружены после ase_library_module_template, что даст следующую очерёдность выполнения операций у модулей: test1, test2, test3, ase_library_module_template.

Тип лицензии модулей#

У каждого модуля можно задать тип лицензии, с каким он поставляется в системе.

Типы лицензии:

Orel
Voronezh
Smolensk

Для того, чтобы задать тип лицензии для модуля, необходимо добавить поле AstraLicense в .ini файл модуля, например:

[General]
ModuleName=ase_library_module_template
ModuleType=Library
Version=1.0
Group=ase_templates
AstraLicense=Voronezh

Так у модуля будет лицензия «Воронеж». Для режима защищённости «Орёл» данный модуль не будет использоваться.

Создание модуля-библиотеки (Library)#

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

Модуль-библиотека представляет из себя библиотеку, в которой хранится функция для инициализации модуля.

В данном разделе рассматривается пример из базовых примеров, в виде модуля-библиотеки ase-library-module.

Объявление класса для модуля-библиотеки#

Файл librarymoduletemplate.h

Новый модуль-библиотека должен наследоваться от ASE::LibrarySettingsModule, в котором должны быть переопределены функции:

userName();
allOptionNames();
getOptionUserName(...);
getSystemValues(...);
setSystemValues(...).

Пример:

#ifndef LIBRARYMODULETEMPLATE_H
#define LIBRARYMODULETEMPLATE_H

#include <AstraSettingsExchange/LibrarySettingsModule>

class LibraryModuleTemplate : public ASE::LibrarySettingsModule
{
    Q_OBJECT

public:
    explicit LibraryModuleTemplate(QObject *parent = nullptr);

    QString userName() const override;

    ASE::OptionNames allOptionNames() const override;
    QString getOptionUserName(const ASE::OptionName &optionName) const override;

    ASE::Error getSystemValues(const ASE::OptionNames &optionNames,
                            ASE::OptionListValues &values) const override;
    ASE::Error setSystemValues(const ASE::OptionMapValues &optionMapValues) const override;
};

#endif // LIBRARYMODULETEMPLATE_H

Объявление функции для инициализации модуля#

Необходимо объявить функцию для инициализации модуля-библиотеки.

Для объявления инициализации модуля-библиотеки можно воспользоваться define ASE_LIBRARY_MODULE(...):

...
ASE_LIBRARY_MODULE(LibraryModuleTemplate);
...

Установка модуля-библиотеки#

Для минимального функционирования модуля-библиотеки, необходимо установить:

Сам модуль-библиотеку, обычно устанавливается в директорию /usr/lib/x86_64-linux-gnu/astra-settings-exchange, где x86_64-linux-gnu - текущая архитектура;
Файл с информацией о модуле, устанавливается в директорию /usr/share/astra-settings-exchange/library-modules.

Имена файла модуля-библиотеки должны иметь следующий шаблон: lib<module_name>.so, где <module_name> - название модуля.

Имена файла с информацией должны иметь следующий шаблон: <module_name>.ini, где <module_name> - название модуля.

Для упрощения установки файлов, можно воспользоваться конфиг-файлом CMake для astra-settings-exchange:

...

find_package(AstraSettingsExchange CONFIG REQUIRED)

...

install(TARGETS ase_library_module_template DESTINATION ${ASE_INSTALL_FULL_LIBDIR})

install(FILES data/ase_library_module_template.ini DESTINATION ${ASE_INSTALL_FULL_LIBRARY_MODULES_DATADIR})

...

Создание собственного дескриптора файлов#

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

Дескриптор файлов - это специальная часть в модуле, которая отвечает за сохранение и загрузку параметров из файла(ов).

Примечание

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

Для изменения работы дескриптора файлов, достаточно сделать класс, унаследованный от класса ASE::AbstractFilesDescriptor, переопределив функции:

fileNames();
getOptionFromFiles();
loadOptions(const OptionNames &optionNames, OptionListValues &values);
saveOptions(const OptionMapValues &optionMapValues).

и назначить экземпляр нового дескриптора файлов для своего модуля, с помощью функции: ASE::AbstractSettingsModule::setFilesDescriptor(AbstractFilesDescriptor *filesDescriptor).

Использование общих действий PolicyKit#

В astra-settings-exchange используется свои общие policykit действия: ru.astralinux.settingsexchange.get и ru.astralinux.settingsexchange.set.

Доступ к этим policy действиям можно получить через функции commonAuthGetAction() и commonAuthSetAction().

Чтобы запрос авторизации происходил не при каждом вызове set и get, а при начале операций экспорта/импорта/получения/изменения, то можно воспользоваться полем isAdminAuthRequired из .ini файла модуля.

Пример:

[General]
ModuleName=ase_library_module_template
ModuleType=Library
Version=1.0
Group=ase_templates
isAdminAuthRequired=True

Создание нативного модуля (Native)#

Перед созданием модуля, рекомендуется заполнить информацию о модуле, разделе «Информация о модуле».

Нативный модуль представляет из себя исполняемый файл.

Создание исполняемого файла#

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

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

Аргумент -n:
- Есть ли дополнительные аргументы: нет;
- Ожидание: вывод в stdout названия модуля;
- Аналог: userName().
Аргумент -l:
- Есть ли дополнительные аргументы: нет;
- Ожидание: вывод в stdout списка всех опций, разделённых переносом стройки(“n“);
- Аналог: allOptionNames().
Аргумент -o:
- Есть ли дополнительные аргументы: да, название опции, обычно без названия модуля.
- Ожидание: вывод в stdout названия опции;
- Аналог: getOptionUserName(...).
Аргумент -g:
- Есть ли дополнительные аргументы: да, названия опций. Название опций помещается как отдельные аргументы: «опция 1», «опция 2», «опция 3» и т.д.
- Ожидание: вывод в stdout со значениями для каждой опции, разделённых переносом стройки(“n“).
- Аналог: getSystemValues(...).
Аргумент -s:
- Есть ли дополнительные аргументы: да, названия опций и их значения. Название опций и их значение помещается как отдельные аргументы: «опция 1», «значение 1», «опция 2», «значение 2»,»опция 3», «значение 3» и т.д.
- Ожидание: .
- Аналог: setSystemValues(...).

С примерами исполняемых файлов, можно ознакомиться на bash (Базовый пример 3) или python (Базовый пример 4).

Установка нативного модуля#

Для минимального функционирования нативного модуля, необходимо установить:

Сам исполняемый файл, устанавливается в директорию /usr/share/astra-settings-exchange/native-modules/executes;
Файл с информацией о модуле, устанавливается в директорию /usr/share/astra-settings-exchange/native-modules/properties.

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

Имена файла с информацией должны иметь следующий шаблон: <module_name>.ini, где <module_name> - название модуля.

Для упрощения установки файлов, можно воспользоваться конфиг-файлом CMake для astra-settings-exchange:

...

find_package(AstraSettingsExchange CONFIG REQUIRED)

...

install(PROGRAMS data/ase_python_module_template.py DESTINATION ${ASE_INSTALL_FULL_NATIVE_MODULES_EXECDIR})

install(FILES data/ase_python_module_template.ini DESTINATION ${ASE_INSTALL_FULL_NATIVE_MODULES_DATADIR})

...

Замечания в проектировании модулей#

Замечание об локализации (переводах) в значениях#

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

Замечание об значениях по умолчанию#

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

Чтобы иметь общее поведение между всеми модулями, то рекомендуется обрабатывать возможность значения QVariant::Invalid([без значения]), так как пользователь astra-settings-exchange может просто в ручную отредактировать файлы или провести импорт только определённых настроек.

Если модуль не поддерживает значение QVariant::Invalid([без значения]), то необходимо при импорте использовать другие фиксированные значения, для значения по умолчанию, например значение в виде строчки DEFAULT или любого другого текста, из которой будет понятно, что это значение по умолчанию.

В случае, когда модуль не поддерживает значения QVariant::Invalid([без значения]), то не стоит завершать работу модуля с ошибкой, при не валидном значении, необходимо писать ошибку в поток вывода stderr, любым доступным способом.

CLI (консольные утилиты)#

astra-settings-import#

Использование: astra-settings-import [параметры] <источник> [группа или модули] [опции]
Утилита для импорта настроек из источника(файл или директория).

Параметры:
    -h, --help              Вывод справки по параметрам командной строки.
    --help-all              Вывод справки с особыми параметрами Qt.
    -m, --modules           Вывод модулей и выход.
    -g, --groups            Вывод групп и выход.
    -p, --properties        Вывод свойств модулей и выход.
    -o, --options <модули>  Вывод опций для модуля(ей) и выход.

Аргументы:
    источник                Путь к источнику(файл или директория) для импорта
                            настроек.
    группа или модули       Имя группы или название модулей, опционально.
                            Используйте символ-разделитель "," или ":", для
                            разделения двух и более названий модулей или групп.
    опции                   Фильтр опций по именам опций, используйте
                            символ-разделитель ";" для разделения двух и более
                            названий опций, в одном аргументе запуска.
                            Поддерживается указание опций, как отдельные аргументы
                            запуска.

astra-settings-export#

Использование: astra-settings-export [параметры] <источник> [группа или модули] [опции]
Утилита для экспорта настроек в источник(файл или директория).

Параметры:
    -h, --help              Вывод справки по параметрам командной строки.
    --help-all              Вывод справки с особыми параметрами Qt.
    -m, --modules           Вывод модулей и выход.
    -g, --groups            Вывод групп и выход.
    -p, --properties        Вывод свойств модулей и выход.
    -o, --options <модули>  Вывод опций для модуля(ей) и выход.

Аргументы:
    источник                Путь к источник(файл или директория) для экспорта
                            настроек.
    группа или модули       Имя группы или название модулей, опционально.
                            Используйте символ-разделитель "," или ":", для
                            разделения двух и более названий модулей или групп.
    опции                   Фильтр опций по именам опций, используйте
                            символ-разделитель ";" для разделения двух и более
                            названий опций, в одном аргументе запуска.
                            Поддерживается указание опций, как отдельные аргументы
                            запуска.

astra-settings-merge#

Использование: astra-settings-merge [параметры] <источник> [группа или модули] [опции]
Утилита для слияния настроек для источника(файл или директория).

Параметры:
    -h, --help              Вывод справки по параметрам командной строки.
    --help-all              Вывод справки с особыми параметрами Qt.
    -m, --modules           Вывод модулей и выход.
    -g, --groups            Вывод групп и выход.
    -p, --properties        Вывод свойств модулей и выход.
    -o, --options <модули>  Вывод опций для модуля(ей) и выход.

Аргументы:
    источник                Путь к источник(файл или директория) с настройками.
    группа или модули       Имя группы или название модулей, опционально.
                            Используйте символ-разделитель "," или ":", для
                            разделения двух и более названий модулей или групп.
    опции                   Фильтр опций по именам опций, используйте
                            символ-разделитель ";" для разделения двух и более
                            названий опций, в одном аргументе запуска.
                            Поддерживается указание опций, как отдельные аргументы
                            запуска.

astra-settings-remove#

Использование: astra-settings-remove [параметры] <источник> [группа или модули] [опции]
Утилита для удаления настроек из источника(файл или директория).

Параметры:
    -h, --help              Вывод справки по параметрам командной строки.
    --help-all              Вывод справки с особыми параметрами Qt.
    -m, --modules           Вывод модулей и выход.
    -g, --groups            Вывод групп и выход.
    -p, --properties        Вывод свойств модулей и выход.
    -o, --options <модули>  Вывод опций для модуля(ей) и выход.

Аргументы:
    источник                Путь к источник(файл или директория) с настройками.
    группа или модули       Имя группы или название модулей, опционально.
                            Используйте символ-разделитель "," или ":", для
                            разделения двух и более названий модулей или групп.
    опции                   Фильтр опций по именам опций, используйте
                            символ-разделитель ";" для разделения двух и более
                            названий опций, в одном аргументе запуска.
                            Поддерживается указание опций, как отдельные аргументы
                            запуска.

Примеры использования#

Примечание

Для примера, будет использоваться система с установленным тестовым модулем ase-library-module-sample, из пакета astra-settings-exchange-samples.

Вывод модулей и опций#

myuser@mypc:~$ astra-settings-export -p
ase-library-module-sample:
    Название: Модуль-пример в библиотечном виде
    Версия: 1.0
    Группа: astra-settings-samples
    Статус: Включён
    Опции:
        bool_example - Логический вариант для теста
        int_example - Целочисленный вариант для теста
        string_example - Строковый вариант для теста
        stringlist_example - Опция списка строк для теста

Экспорт настроек в файл#

astra-settings-export test.tar.gz

Экспорт настроек в директорию#

Предупреждение

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

astra-settings-export ./

Импорт настроек из файла#

astra-settings-import test.tar.gz

Импорт настроек из директории#

Предупреждение

Если указать пустую директорию, то могут «обнулиться» настройки системы, данное поведение не определено.

astra-settings-import ./

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

astra-settings-export test.tar.gz ase_system_parameters astra-macros-lock astra-overlay

astra-settings-export test.tar.gz ase_system_parameters:ase-settings-dm ase_system_parameters:astra-macros-lock ase-settings-dm:security_settings/UserList

Обмен настроек - astra-settings-exchange

Содержание

Обмен настроек - astra-settings-exchange#

Архитектура#

О механизме#

Модуль#

Название настроек (опций)#

Файл для настроек#

Процедура импорта настроек#

Процедура экспорта настроек#

Как работает чтение/запись файлов в модулях#

Создание модулей настроек в astra-settings-exchange#

Базовые примеры#

Типы модулей#

Информация о модуле#

Файл информации о модуле#

Зависимости модулей#

Тип лицензии модулей#

Создание модуля-библиотеки (Library)#

Объявление класса для модуля-библиотеки#

Объявление функции для инициализации модуля#

Установка модуля-библиотеки#

Создание собственного дескриптора файлов#

Использование общих действий PolicyKit#

Создание нативного модуля (Native)#

Создание исполняемого файла#

Установка нативного модуля#

Замечания в проектировании модулей#

Замечание об локализации (переводах) в значениях#

Замечание об значениях по умолчанию#

CLI (консольные утилиты)#

astra-settings-import#

astra-settings-export#

astra-settings-merge#

astra-settings-remove#

Примеры использования#

Вывод модулей и опций#

Экспорт настроек в файл#

Экспорт настроек в директорию#

Импорт настроек из файла#

Импорт настроек из директории#

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