Команды

Команда — это сущность SALT.BOX, представляющая вызов команды salt на контроллере.
Команда содержит параметры вызова команды salt, обеспечивает ее выполнение и представление пользователю статуса выполнения, промежуточных и окончательных результатов выполнения.

Создание команды

Создание команды из карточки клиента

Чтобы перейти в карточку клиента, в пункте Клиенты перейдите на вкладку Список.
Далее выберите нужного клиента и нажмите кнопку открывающую карточку клиента Рис. 1.

Рисунок 1. Переход из списка клиентов в карточку клиента

В карточке клиента перейдите на вкладку Ответы команд и нажмите кнопку +Создать команду Рис. 2.

Рисунок 2. Карточка клиента. Вкладка "Ответы команд"

Будет выведено диалоговое окно Выберите функцию Рис. 3.

Рисунок 3. Диалоговое окно "Выберите функцию"

После выбора функции откроется диалоговое окно Настройки команды, при этом в полях Тип цели Рис. 4 [1] и Цель
Рис. 4 [2] будут указаны необходимые значения: тип нацеливания и идентификатор клиента Рис. 4.

Рисунок 4. Диалоговое окно "Настройки команды"

к сведению

Для параметризации команды (например, добавить параметр Время ожидания ответа команды Рис. 4 [4]) есть функция Расширенные настройки.
Для этого на вкладке Настройки необходимо активировать кнопку Расширенные настройки Рис. 4 [3].

После настройки команды нажмите кнопку Создать Рис. 4 [5].

Создание команды со страницы команд

Для создания команды со страницы команд в главном меню выберите пункт Команды Рис. 5.
Далее на странице команд нажмите кнопку +Создать команду, расположенную в верхней левой части страницы Рис. 5.
Будет выведено диалоговое окно Выберите функцию Рис. 3 и после выбора функции откроется диалоговое окно Настройки команды Рис. 4.
При этом в поле Тип цели Рис. 4 [1] будет указано значение по умолчанию — glob, а поле Цель Рис. 4 [2] будет со знаком "*".

Рисунок 5. Переход из пункта Команды на страницу Карточки клиента. Кнопка "+Создать команду"

к сведению

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

Выбор функции

Выбор функции осуществляется в диалоговом окне Выберите функцию Рис. 3.
В таблице 1 приведён перечень доступных функций.

Таблица 1. Функции модулей выполнения

Группа функций	Функция	Назначение
cmd	cmd.run	Выполнить переданную команду и вернуть вывод в виде строки
cp	cp.get_dir	Используется для рекурсивного копирования каталога с контроллера SALT.BOX
	cp.get_file	Загрузить файл с URL в каталог кэша клиента и вернуть содержимое этого файла. Возвращает False, если Salt не удалось кэшировать файл с URL
	cp.get_url	Используется для получения одного файла с URL
disk	disk.blkid	Возвращает атрибуты блочного устройства: UUID, LABEL и т. д. Эта функция работает только в системах, где доступен blkid
	disk.fstype	Возвращает имя файловой системы указанного устройства
	disk.get_fstype_from_path	Возвращает тип файловой системы базового устройства для указанного пути
	disk.usage	Возвращает информацию об использовании для томов, смонтированных на этом клиенте
file	file.chgrp	Сменить группу файла
	file.chown	Сменить владельца файла, установить указанные пользователя и группу файла
	file.diskusage	Рекурсивно рассчитать использование диска по указанному пути и вернуть это значение в байтах
	file.grep	Выполнить grep указанной строки в указанном файле
	file.line	Построчное редактирование файла
	file.link	Создать жесткую ссылку на файл
	file.mkdir
	file.move	Переместить файл или каталог
	file.read	Вернуть содержимое файла
	file.readdir	Вернуть список, содержащий содержимое каталога
	file.rmdir	Удалить указанный каталог
	file.stats	Вернуть словарь, содержащий статистику для указанного файла
	file.touch	Аналогично команде touch — создать файл, если он не существует, или обновить atime и mtime, если файл существует
grains	grains.append	Добавить значение в список в файле конфигурации grains. Если grain не существует, добавляется ключ grain, а значение добавляется к новому grain как элемент списка
	grains.delkey	Полностью удалить grain, т.е. удалить ключ и значение grain
	grains.item	Вернуть один или несколько элементов grain
	grains.items	Вернуть все элементы grains клиента
	grains.set	Установить ключ в произвольное значение. Функция используется как setval, но работает с вложенными ключами. Эта функция консервативна. Она перезапишет запись, только если ее значение и заданное значение не являются списком или словарем. Параметр force используется для разрешения перезаписи во всех случаях
mount	mount.active	Вернуть список активных смонтированных файловых систем
	mount.fstab	Просмотреть содержимое fstab
	mount.get_device_from_path	Вернуть базовое устройство для указанного пути
	mount.get_mount_from_path	Вернуть смонтированную файловую систему, предоставляющую указанный путь
	mount.mount	Смонтировать устройство
	mount.remount	Попытаться перемонтировать устройство. Если устройство еще не смонтировано, вызывается mount
	mount.swaps	Вернуть словарь, содержащий информацию об активном swap
	mount.umount	Попытаться размонтировать устройство, указав каталог, в который оно смонтировано
network	network.active_tcp	Вернуть словарь, содержащий информацию обо всех запущенных TCP-соединениях (в настоящее время только для Linux и Solaris)
	network.arp	Вернуть таблицу arp клиента
	network.connect	Проверить подключение к хосту с использованием определенного порта клиента
	network.default_route	Вернуть маршрут(ы) по умолчанию из таблицы маршрутизации
	network.dig	Выполнить DNS-поиск с помощью dig
	network.fqdns	Вернуть все известные FQDN для системы перебором всех интерфейсов с попытками выполнить обратное разрешение (исключая интерфейс 'lo')
	network.get_fqdn	Получить полное доменное имя
	network.get_hostname	Получить имя хоста
	network.get_route	Вернуть информацию о маршрутизации для указанного IP-адреса назначения
	network.hwaddr	Вернуть аппаратный адрес (MAC-адрес) заданного интерфейса
	network.interface	Вернуть адрес inet для заданного интерфейса
	network.interfaces	Вернуть словарь информации обо всех интерфейсах клиента
	network.ip_addrs	Вернуть список адресов IPv4, назначенных хосту. 127.0.0.1 игнорируется, если не указано 'include_loopback=True'. Если указано 'interface', то будут возвращены только IP-адреса этого интерфейса. Указание CIDR 'cidr="10.0.0.0/8"' вернет только адреса, которые находятся в этой подсети. Если 'type' = 'public', то будут возвращены только публичные адреса. Аналогично для 'type'='private'
	network.mod_hostname	Изменить имя хоста
	network.netstat	Вернуть информацию об открытых портах и ​​состояниях
	network.ping	Выполнить ICMP-пинг на хост
	network.routes	Вернуть текущие настроенные маршруты из таблицы маршрутизации
	network.subnets	Возвращает список подсетей IPv4, к которым принадлежит хост
	network.traceroute	Выполнить трассировку маршрута на сторонний хост
	network.wol	Отправить пакет Wake On Lan на хост
pillar	data	Получить и отобразить полные, скомпилированные данные pillars, назначенные конкретному клиенту
	fetch	Получить значения из данных pillars внутри SLS и Jinja-шаблонов. При отсутствии ключа pillar в данных pillars — возвращает значение по умолчанию
	file_exists	Выполнить поиск и проверить наличие pillar-файла без его загрузки и применения. Функция доступна только для контроллера SALT.BOX. Путь к файлу задается через данные pillars клиента
	filter_by	Выбрать (провести фильтрацию) значение (или набор значений) из данных pillars на основе указанного ключа pillar
	get	Получить одно значение по ключу pillar из данных pillars клиента. При отсутствии ключа pillar в данных pillars — возвращает значение по умолчанию
	item	Получить значения одного или нескольких указанных ключей из данных pillars клиента
	items	Получить полный набор данных pillars клиента (полный список ключей и значений)
	keys	Получить набор ключей (без значений) верхнего уровня из данных pillars клиента
	ls	Аналогично функции keys, предоставить набор ключей (без значений) верхнего уровня из данных pillars клиента
	obfuscate	Аналогично функции items, но замаскировать значения указанных ключей в выводе данных pillars клиента, заменить реальные значения данных на маскировочную строку (по умолчанию — это XXXXXXXXXXXX)
	raw	Возвращает необработанные (сырые) данные pillars, которые в данный момент присутствуют у клиента. В отличие от items, эта функция не обращается к контроллеру SALT.BOX для получения актуальных данных pillars
saltutil	saltutil.kill_all_jobs	Отправить сигнал kill (SIGKILL 9) всем текущим работающим заданиям
	saltutil.kill_job	Отправить сигнал kill (SIGKILL 9) процессу указанного задания salt
	saltutil.running	Вернуть данные обо всех работающих процессах salt на minion
	saltutil.sync_all	Синхронизировать все динамические модули с файлового сервера для определенной среды. Эта функция синхронизирует пользовательские модули, состояния (states), маяки (beacons), grains, модули возврата (returners), модули вывода (output modules), рендереры (renderers) и утилиты
	saltutil.sync_grains	Синхронизировать модули grains клиента с salt://_grains
	saltutil.sync_modules	Синхронизировать модули выполнения клиента с salt://_modules
	saltutil.sync_states	Синхронизировать модули состояния клиента с salt://_states
state	state.apply	Эта функция вызовет state.highstate <salt.modules.state.highstate> или state.sls <salt.modules.state.sls> в зависимости от аргументов, переданных этой функции
systemd_service	systemd_service.available
	systemd_service.disable	Отключить указанную службу (запретить запуск при загрузке системы)
	systemd_service.disabled	Вывести, запрещён ли запуск указанной службы при загрузке системы
	systemd_service.enable	Включить запуск указанной службы при загрузке системы
	systemd_service.get_all	Вернуть список всех доступных служб
	systemd_service.mask	Замаскировать указанную службу с помощью systemd
	systemd_service.masked	Проверить, замаскирована ли служба
	systemd_service.restart	Перезапустить указанную службу с помощью systemd
	systemd_service.show	Показать свойства одного или нескольких юнитов/задач или менеджера
	systemd_service.status	Возвращает статус службы через systemd. Если имя содержит подстановку, возвращается словарь, сопоставляющий имя службы со значениями True/False
	systemd_service.stop	Остановить указанную службу с помощью systemd
test	test.echo	Вернуть указанную строку — используется для проверки соединения
	test.ping	Используется для проверки работоспособности и ответа клиента. Не является ICMP-пингом
	test.rand_sleep	Перейти в состояние сна на случайное количество секунд. Используется для проверки длительных команд и клиентов, отвечающих с разными интервалами
	test.version	Вернуть версию Salt на клиенте
	test.versions	Вернуть версии компонентов, используемых salt
win_service	win_service.available	Проверить, доступна ли служба в системе
	win_service.delete	Удалить указанную службу
	win_service.disable	Отключить запуск указанной службы при загрузке системы
	win_service.disabled	Проверить, отключен ли запуск указанной службы при загрузке системы
	win_service.enable	Включить запуск указанной службы при загрузке системы
	win_service.enabled	Проверить, включен ли запуск указанной службы при загрузке системы
	win_service.get_all	Вернуть список всех установленных служб
	win_service.get_disabled	Вернуть список отключенных служб. Отключенная служба определяется как служба, помеченная как 'Отключено' или 'Вручную'
	win_service.get_enabled	Вернуть список включенных служб. Включенная служба определяется как служба, отмеченная как Auto Start
	win_service.getsid	Вернуть SID этой службы Windows
	win_service.info
	win_service.missing	Значение, обратное возвращаемому функцией win_service.available
	win_service.restart	Перезапустить указанную службу. Службе передается команда stop, за которой следует start
	win_service.start	Запустить указанную службу
	win_service.status	Вернуть статус службы. Если имя службы содержит подстановку, возвращается словарь, сопоставляющий имя службы со значениями True/False
	win_service.stop	Остановить указанную службу

примечание

Укажите аргументы, если их принимает функция.

Выбор типа нацеливания, указание цели

В выпадающем списке Тип цели выберите тип нацеливания Рис. 6.
От выбора типа нацеливания зависит способ интерпретации поля Цель — цели, указывающей на отдельного клиента или группу клиентов.
Сведения о типах нацеливания приведены в таблице 2.

Рисунок 6. Выбор типа нацеливания для новой команды

Таблица 2. Типы нацеливания

Тип нацеливания	Значение	Пояснение
glob	Подстановка в стиле bash	Сопоставление по умолчанию, которое используется в SaltStack, — это подстановка в стиле оболочки bash вокруг идентификатора клиента (glob)
pcre	Регулярное выражение в стиле Perl	Использовать pcre-выражения
list	Python-список хостов	Использовать список, разделённый запятыми
grain	Сопоставление с grains	Использовать значения элементов grain. Синтаксис: ключ элемента grain и следующее за ним glob-выражение, например: os:Alt*
grain_pcre	Сопоставление с grains в сочетании с регулярным выражением	Использовать значения элементов grain. Синтаксис: ключ элемента grain и следующее за ним pcre-выражение, например: os:Alt.*
pillar	Сопоставление с данными pillar	Использовать значение pillar. Синтаксис: ключ элемента pillar и следующее за ним glob-выражение, например: role:production*
pillar_pcre	Сопоставление с данными pillar в сочетании с регулярным выражением	Использовать значение pillar. Синтаксис: ключ элемента pillar и следующее за ним pcre-выражение, например: role:prod.*
nodegroup	Сопоставление с nodegroup	Использовать одну из предопределённых групп узлов
range	Использовать сервер Range для сопоставления	Использовать выражение для диапазона (например, %cluster). Использование параметра Range требует настройки сервера диапазона и указания его местоположения в главном файле конфигурации
compound	Использовать составное нацеливание	Опция "составная цель" позволяет использовать цели нескольких типов в одном выражении, обеспечивая высокую степень детализации сопоставления. Цели разных типов в выражении разделены пробелами и логическими операторами not, and, or; перед целями, отличными от glob, стоит идентификатор, соответствующий типу аргумента конкретной цели, например: salt 'G@os:RedHat and webser* or E@database.*'
ipcidr	Сопоставление на основе подсети (нотация CIDR) или адреса IPv4	Сопоставление по подсети (в нотации CIDR) или IP-адресу

В поле Цель укажите цель команды — выражение в зависимости от выбранного типа нацеливания.

Подтверждение создания команды

Нажмите кнопку Создать Рис. 7.

Рисунок 7. Диалоговое окно создания команды

Команда будет создана, отобразится окно с карточкой команды Рис. 8.

к сведению

Выполнение команды начинается немедленно после создания.

Карточка команды

Рисунок 8. Карточка команды

Карточка команды состоит из следующих основных блоков и элементов интерфейса:

• блок атрибутов команды и кнопка Повторить команду Рис. 8 [1]

  перечень атрибутов команды приведён в таблице 3.
  Кнопка Повторить команду открывает окно Настройки команды и позволяет перезапустить команду или изменить его параметры

• блок статусов команды (сводка результата) Рис. 8 [2]

  перечень статусов команды приведён в таблице 5

• кнопка Обновить Рис. 8 [3]

  обновляет таблицу клиентов

• кнопка Выгрузить в CSV Рис. 8 [4]

  выгружает табличный результат в виде файла в формате CSV

• вкладки с режимами отображения Рис. 8 [5]:

  • Стандартный — текущий вид (краткий);
  • Подробный — больше деталей (stdout, stderr и т.д.);
  • Табличный — компактный список
  к сведению

  Для команд, выполненных с использованием функции state.apply, доступен дополнительный режим (вкладка) отображения результатов — state.apply.

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

  В данном режиме отображаются:

  • выполненные состояния;
  • успешные и ошибочные шаги;
  • пропущенные шаги (например, при использовании условий onlyif, unless, creates);
  • сообщения выполнения (stdout, stderr, comment);
  • результаты зависимостей (require) и связанные изменения.

• таблица клиентов с результатом выполнения команды Рис. 8 [6]

  на вкладке Стандартный Рис. 8 [5] отображается список обработанных целей (клиентов, на которые доставлена команда)

В таблице 3 приведён перечень атрибутов команды.

Таблица 3. Перечень атрибутов команды

Атрибут	Описание
Контроллер	Сервер управления (контроллер SALT.BOX)
Тип цели	Тип нацеливания
Цели	Цель команды
Функция	Функция модуля выполнения
Аргументы	Позиционные аргументы
Именованные аргументы	Справочник именованных аргументов
Пользователь	Пользователь, создавший команду
Длительность выполнения	Временной отрезок между началом и завершением выполнения команды

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

Граф выполнения команды

На Рис. 9 показан граф выполнения команды.

Условия переходов между статусами команды приведены в таблице 4.

Рисунок 9. Граф выполнения команды

Таблица 4. Таблица переходов графа выполнения команды

Метка дуги	Условие перехода
1	Контроллер SALT.BOX принял и запустил команду
2	Выполнено успешно (retcode = 0)
3	Выполнено с ошибкой (retcode ≠ 0)
4	Превышено время выполнения
5	Клиент не существует
6	Получены статусы возврата ответов от всех клиентов, попавших в нацеливание
7	Ошибка запуска команды

Результаты выполнения команды

При нажатии значка + слева от записи клиента открывается поле со значением ключа data (результат выполнения функции) Рис. 8 [6].
Для того чтобы получить более детальную информацию о выводе результатов, нажмите на вкладку Подробный Рис. 10.
В результате откроется JSON-выражение — ответ, полученный от клиента Рис. 10.

Рисунок 10. Карточка команды. Кнопка "Подробный"

примечание

Записи в таблице клиентов появляются по мере получения от них ответов.

В таблице 5 приведён перечень полей таблицы клиентов.

Таблица 5. Перечень полей таблицы клиентов

Атрибут	Значение
MID	Идентификатор клиента
Статус	Статусы выполнения: Успешно (Success) — команда выполнилась без ошибок и вернула корректный результат. Выполнение завершено с допустимым кодом возврата; Ошибка (Failed) — команда начала выполняться, но завершилась с ошибкой. Результат содержит сообщение об ошибке или недопустимый код возврата; Тайм-аут (Timeout) — команда была отправлена клиенту, но результат выполнения не был получен в течение заданного времени ожидания. Причина может быть связана с недоступностью клиента или длительным выполнением; Игнорировано (Ignored) — означает, что указанный клиент не существует в системе (отсутствует на контроллере SALT.BOX и среди клиентов) на момент выполнения, поэтому команда не может быть доставлена и игнорируется; Ожидание (Waiting) — команда была отправлена клиенту, выполнение ещё продолжается, и результат на момент формирования статуса не получен
Код возврата	Код возврата функции
Время выполнения	Время ответа клиента
Длительность выполнения	Временной интервал между началом выполнения команды и ответом клиента

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

Рисунок 11. Карточка команды в табличном представлении

к сведению

Подсказка Отображается 1 Job Return. В таблице представлены только успешно выполненные Job Return Рис. 11 означает что:

• Сейчас показан только 1 результат выполнения (Job Return);
• В режиме Табличный система выводит только успешные ответы;
• Результаты со статусами Игнорировано, Тайм-аут, Ожидание или Ошибка в таблицу не включаются.

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

• В режиме Подробный — отображается «сырой» или отформатированный древовидный текст (это удобно для отладки сложных структур данных).

• В режиме Табличный — система анализирует ключи в JSON-объекте и преобразует их в столбцы, а значения — в строки.