Перейти к содержанию

Что такое функция?

функция — это описание, которое преобразует некоторые именованные значения (его параметры) в команду оболочки. Каждый кнопка в вашем меню называет ровно одну функцию в своем Поле function.

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

Что происходит, когда вы нажимаете кнопку

  1. Бот ищет функцию, указанную в поле function кнопки.
  2. Он собирает значения, написанные на этой кнопке.
  3. На основе этих значений создается одна команда оболочки.
  4. Он запускает команду в оболочка и отправляет выходные данные. вернуться в чат в виде блока кода.

Если функция не существует или отсутствует необходимое ей значение, бот не запускается: validate первым сообщает о проблеме.

Рабочий пример

Функция command встроена и всегда доступна. Он запускает все, что вы напишите в поле кнопки command.

Использовать встроенную командную функцию

Uptime button
- name: Uptime
  type: button
  function: command
  command: "uptime"

Нажмите Время работы, и бот запустит uptime на сервере и отправит выходные данные обратно.

Передача значений из кнопки

Напишите каждое значение непосредственно на кнопке. Есть два способа сделать это:

  1. Используйте поля ярлыков command, path и args. Каждый заполняет параметр с тем же именем.
  2. Для любого другого параметра используйте его имя в качестве клавиши на кнопке.

Передать URL-адрес по имени параметра

Check API button
- name: Check API
  type: button
  function: curl-url
  url: "https://example.com/health"

Здесь url соответствует параметру url, объявленному curl-url. То же правило работает для таких имен, как host, unit и lines.

Не помещайте значения внутри params:

params: принадлежит файлу пользовательской функции, где он объявляет значения эта функция принимает. На кнопке напишите каждое значение напрямую:

Values belong directly on the button
- name: Nginx logs
  type: button
  function: journal-unit
  unit: "nginx.service"
  lines: 100

Числовые значения YAML не нуждаются в кавычках.

validate проверяет каждый ключ по параметрам объявленный выбранной функцией. Ошибка в написании или необъявленном имени не проходит проверку. Команда также проверяет значения, объявленные как int или bool. Необязательные значения используют значения по умолчанию, когда кнопка не включает их.

Два вида функций

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

Встроенный Пользовательский
Откуда это взялось Поставляется внутри программы Файл YAML, который вы пишете
Вы создаете файл? Нет Да, по одному файлу на функцию
Имена Зарезервировано (command, script) Любое незарезервированное имя
Всегда доступна? Да Только если вы установите function_directory
Можно изменить? Нет Да, это ваши файлы

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

Встроенные функции

Две функции загружаются всегда, даже если вы не задали function_directory. Их поля command, path и args идут прямо дальше. кнопка.

Функция Что она делает Требуется Необязательно
command Запускает одну команду оболочки, как написано command —
script Запускает файл сценария с аргументами path args

Оба имени зарезервированы. Файл пользовательских функций не может повторно использовать их: загрузчик останавливается с ошибкой типа function name "command" is reserved, и бот не запускается.

Пользовательские функции

Пользовательская функция — это отдельный файл YAML, описывающий одну команду многократного использования. Сохраните эти файлы в своей папке и укажите function_directory на это.

Сообщите боту, где находятся ваши файлы функций

config.yaml
function_directory: "./functions"

Бот читает эту папку при запуске, включая подпапки, и выбирает каждый файл .yaml и .yml в нем. Другие файлы игнорируются.

В архиве релиза уже есть папка functions/ с пятью примерами. вы можете использовать как есть:

Функция Что она делает Значения кнопок
Эхо-скрипт Запускает скрипт через Bash path, необязательно args
Использование диска Показывает использование диска необязательно path
Запрос URL Получает URL url
Пинг хоста Проверяет доступность хоста host, необязательно count
Единица журнала Показывает последние журналы обслуживания unit, необязательно lines

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

Проверьте, что загрузилось

List every function the bot can see
./telegram-commander list-functions --config config.yaml

Встроенные функции показывают source=builtin; пользовательские показывают файл, который они пришел из.

Указания по безопасности

Кнопки запускаются с правами бота

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

Значения параметров вставляются в команду в виде текста. Относитесь к ним как к ввод оболочки: отдайте предпочтение фиксированным значениям на кнопках и добавьте confirm: true ко всему разрушительному.

Длинный вывод сохраняется, а затем доставляется

Команды останавливаются на своём timeout, и бот сохраняет не больше max_output_bytes их вывода. А что дойдёт до чата — несколько сообщений или один файл .txt — решает output. См. Управление выводом.

Похожие