BUSCTL(1)

busctl

BUSCTL(1)

НАЗВА

busctl - глибинний аналіз каналу обміну даними

КОРОТКИЙ ОПИС

busctl [ПАРАМЕТРИ...] [КОМАНДА] [НАЗВА...]

ОПИС

busctl можна скористатися для глибинного аналізу та спостереження за каналами обміну даними D-Bus.

КОМАНДИ

Передбачено обробку таких команд:

list

Вивести усі вузли на каналі за назвами їхніх служб. Типово, показує унікальні та загальновідомі назви, але це можна змінити за допомогою перемикачів --unique і --acquired. Це типова дія, якщо не вказано команди.

Додано у версії 209.

status [СЛУЖБА]

Вивести дані щодо процесу та реєстраційні дані служби каналу (якщо таку вказано за її унікальною та загальновідомою назвою), процес (якщо такий вказано за його числовим PID) або власника каналу (якщо не вказано жодного параметра).

Додано у версії 209.

monitor [СЛУЖБА...]

Створити дамп обміну повідомленнями. Якщо вказано параметр СЛУЖБА, вивести повідомлення до цього вузла і від цього вузла за ідентифікацією за загальновідомою або унікальною назвою. Якщо параметр не вказано, вивести усі повідомлення на каналі. Скористайтеся Ctrl+C для переривання виведення дампу.

Додано у версії 209.

capture [СЛУЖБА...]

Подібна до команди monitor, але записує виведені дані у форматі pcapng (щоб дізнатися більше, див. Формат файлів захоплених даних PCAP Next Generation (pcapng)[1]). Не забудьте, переспрямувати стандартне виведення до файла або каналу. Для аналізу та перегляду файлів-результатів можна скористатися інструментами, подібними до wireshark(1).

Додано у версії 218.

tree [СЛУЖБА...]

Показує ієрархію об'єктів однієї або декількох служб. Якщо вказано параметр СЛУЖБА, вивести ієрархію об'єктів лише для вказаних служб. Якщо параметр не вказано, вивести ієрархії для усіх об'єктів усіх служб на каналі, які отримали принаймні одну загальновідому назву.

Додано у версії 218.

introspect СЛУЖБА ОБ'ЄКТ [ІНТЕРФЕЙС]

Вивести інтерфейси, методи, властивості та сигнали вказаного об'єкта (ідентифікується за шляхом до нього) на вказаній службі. Якщо передано аргумент інтерфейсу, виведення буде обмежено членами вказаного інтерфейсу.

Додано у версії 218.

call СЛУЖБА ОБ'ЄКТ ІНТЕРФЕЙС МЕТОД [ПІДПИСE [АРГУМЕНТ...]]

Викликати метод і вивести відповідь. Приймає назву служби, шлях до об'єкта, назву інтерфейсу та назву методу. Якщо виклику методу слід передати параметри, потрібен рядок підпису, після його слід вказати аргументи, окремо форматовані як рядки. Подробиці форматування наведено нижче. Щоб придушити виведення повернених даних, скористайтеся параметром --quiet.

Додано у версії 218.

emit ОБ'ЄКТ ІНТЕРФЕЙС СИГНАЛ [ПІДПИС [АРГУМЕНТ...]]

Видати сигнал. Приймає шлях до об'єкта, назву інтерфейсу і назву методу. Якщо виклику методу слід передати параметри, потрібен рядок підпису, після його слід вказати аргументи, окремо форматовані як рядки. Подробиці форматування наведено нижче. Щоб вказати призначення сигналу, скористайтеся параметром --destination=.

Додано у версії 242.

get-property СЛУЖБА ОБ'ЄКТ ІНТЕРФЕЙС ВЛАСТИВІСТЬ...

Отримати поточне значення однієї або декількох властивостей об'єкта. Приймає назву служби, шлях до об'єкта, назву інтерфейсу та назву властивості. Можна вказати одразу декілька властивостей. У цьому випадку їхні значення буде виведено одне за одним, відокремлені символами нового рядка. Дані буде, типово, виведено у скороченому форматі. Скористайтеся параметром --verbose, щоб зробити виведені дані докладнішими.

Додано у версії 218.

set-property СЛУЖБА ОБ'ЄКТ ІНТЕРФЕЙС ВЛАСТИВІСТЬ ПІДПИС АРГУМЕНТ...

Встановити поточне значення властивості об'єкта. Приймає назву служби, шлях до об'єкта, назву інтерфейсу, назву властивості, підпис властивості, а далі, список параметрів, які форматовано як рядки.

Додано у версії 218.

help

Вивести довідку щодо синтаксису команд.

Додано у версії 209.

ПАРАМЕТРИ

Передбачено обробку таких параметрів:

--address=АДРЕСА

Встановити з'єднання із каналом, який задано параметром АДРЕСА, замість використання відповідних типових значень для системного каналу або каналу користувача (див. параметри --system і --user).

Додано у версії 209.

--show-machine

При виведенні списку вузлів вивести стовпчик, що містить назви контейнерів, до яких вони належать. Див. systemd-machined.service(8).

Додано у версії 209.

--unique

При виведенні списку вузлів, виводити лише «унікальні» назви (у формі ":число.число").

Додано у версії 209.

--acquired

Протилежність до --unique — буде виведено лише «загальновідомі» назви.

Додано у версії 209.

--activatable

При виведенні списку вузлів вивести лише вузли, які насправді ще не активовано, але які може бути запущено автоматично при запиті щодо доступу.

Додано у версії 209.

--match=ВІДПОВІДНИК

При виведенні обміну повідомленнями виводити лише підмножину, яка відповідає взірцю ВІДПОВІДНИК. Див. sd_bus_add_match(3).

Додано у версії 209.

--size=

Якщо використано з командою capture, вказує максимальний розмір повідомлення каналу для захоплення ("snaplen"). Типовим значенням є 4096 байтів.

Додано у версії 218.

--list

Якщо використано з командою tree, виводить простий список шляхів об'єктів замість ієрархічного.

Додано у версії 218.

-q, --quiet

Якщо використано з командою call, придушити показ вмісту повідомлень-відповідей. Зауважте, що якщо вказано цей параметр, повідомлення про помилки все одно буде виведено, а інструмент повідомить про успіх або помилку за допомогою коду виходу з процесу.

Додано у версії 218.

--verbose

Якщо використано з командою call або get-property, виводить дані у докладнішому форматі.

Додано у версії 218.

--xml-interface

Якщо використано з командою introspect, створити дамп опису XML, який отримано від виклику D-Bus org.freedesktop.DBus.Introspectable.Introspect, замість звичайного виведення.

Додано у версії 243.

--json=РЕЖИМ

Якщо використано з командою call або get-property, виводить дані із форматуванням JSON. Аргументами можуть бути такі рядки: "short" (найскороченіше виведення без додаткових пробілів та розбиття на рядки) або "pretty" (форматована версія із відступами та розбиттям на рядки). Зауважте, що перетворення з упорядкованих даних D-Bus до JSON відбувається без втрат, що означає, що дані щодо типу буде вбудовано до ієрархії об'єктів JSON.

Додано у версії 240.

-j

Еквівалент --json=pretty, якщо викликано інтерактивно з термінала. Якщо це не так, еквівалент --json=short, зокрема, якщо виведення передається конвеєром якійсь іншій програмі.

Додано у версії 240.

--expect-reply=БУЛЕВЕ ЗНАЧЕННЯ

Якщо використано з командою call, вказує, чи має busctl очікувати на завершення виклику методу, виведення повернутих даних відповіді методу і повернення повідомлення про успіх або помилку за допомогою коду виходу процесу. Якщо встановлено значення "no", буде видано виклик методу, але програма не очікуватиме на відповідь, роботу інструмента буде негайно перервано, отже, відповідь не виводитиметься, а дані щодо успіху або помилки не буде повернуто за допомогою коду виходу з програми. Щоб просто придушити виведення вмісту повідомлення-відповіді, скористайтеся --quiet, яку описано вище. Типовим варіантом є "yes".

Додано у версії 218.

--auto-start=БУЛЕВЕ ЗНАЧЕННЯ

Якщо використано з командою call або emit, вказує, чи має виклик методу неявним чином активувати викликану службу, якщо її ще не запущено, але налаштовано на автоматичний запуск. Типовим варіантом є "yes".

Додано у версії 218.

--allow-interactive-authorization=БУЛЕВЕ ЗНАЧЕННЯ

Якщо використано з командою call, вказує, чи можуть служби примусово вимагати інтерактивного уповноваження під час виконання дії, якщо правила захисту налаштовано належним чином. Типовим варіантом є "yes".

Додано у версії 218.

--timeout=СЕКУНДИ

Якщо використано з командою call, визначає максимальний час очікування для доповнення виклику методу. Якщо не вказано одиницю часу, неявним чином буде використано секунди. Програма може розпізнавати звичайні інші одиниці (ms, us, s, min, h, d, w, month, y). Зауважте, що цей час очікування не буде застосовано, якщо використано --expect-reply=no, оскільки програма у цьому випадку не очікуватиме на жодне повідомлення-відповідь. Якщо не вказано або якщо встановлено значення 0, буде використано типове значення "25s".

Додано у версії 218.

--augment-creds=БУЛЕВЕ ЗНАЧЕННЯ

Керує тим, чи слід доповнювати реєстраційні дані, про які повідомлено list або status, даними з /proc/. Якщо увімкнено, виведені дані, можливо, будуть несумісними, оскільки дані, які прочитано з /proc/, можуть бути новішими за решту реєстраційних даних. Типовим значенням є "yes".

Додано у версії 218.

--watch-bind=БУЛЕВЕ ЗНАЧЕННЯ

Керує тим, чи слід очікувати на появу вказаного сокета каналу AF_UNIX у файловій системі до встановлення з'єднання з ним. Типово, очікування вимкнено. Якщо увімкнено, інструмент стежитиме за файловою системою до створення сокета, а потім встановлюватиме з ним з'єднання.

Додано у версії 237.

--destination=СЛУЖБА

Приймає назву служби. Якщо використано з командою emit, для вказаної служби буде видано сигнал.

Додано у версії 242.

--user

Обмінюватися даними із засобом керування службами користувача, який викликав команду, а не з засобом керування службами системи.

--system

Обмінюватися даними із загальносистемним засобом керування службами. Це неявний типовий варіант.

-H, --host=

Виконати дію віддалено. Вкажіть назву вузла або відокремлені символом «@» ім'я користувача і назву вузла, з якими слід встановити з'єднання. До назви вузла можна дописати суфікс порту, на якому очікуватиме на з'єднання ssh. Суфікс має бути відокремлено двокрапкою. Далі, можна вказати назву контейнера, відокремлену «/», яка вказуватиме що з'єднання слід встановити безпосередньо із вказаним контейнером на вказаному вузлі. Для обміну даними із екземпляром засобу керування на віддаленому комп'ютері буде використано SSH. Назви контейнерів можна нумерувати за допомогою machinectl -H ВУЗОЛ. Адреси IPv6 слід брати у квадратні дужки.

-M, --machine=

Виконати дію у локальному контейнері. Вкажіть назву контейнера, з якими слід встановити з'єднання, із необов'язковим префіксом імені користувача, який слід відокремити від назви контейнера символом «@». Якщо замість контейнера використати особливий рядок «.host», буде встановлено з'єднання із локальною системою (це корисно для встановлення з'єднання із каналом даних певного користувача: «--user --machine=lennart@.host»). Якщо не буде використано синтаксичної конструкції із «@», буде встановлено з'єднання від імені користувача root. Якщо використано «@», ліву чи праву частину синтаксичного виразу навколо нього може бути пропущено (але не обидві частини). У цьому випадку неявно буде використано ім'я локального користувача і «.host», відповідно.

-l, --full

Не обривати багатокрапкою виведення команди list.

Додано у версії 245.

--no-pager

Не передавати виведені дані до засобу поділу на сторінки.

--no-legend

Не виводити умовні позначення, тобто заголовки і підвали стовпчиків із підказками.

-h, --help

Вивести короткий текст довідки і завершити роботу.

--version

Вивести короткі дані щодо версії і завершити роботу.

ФОРМАТУВАННЯ ПАРАМЕТРІВ

Команди call і set-property приймають рядок підпису, за яким слід вказати список параметрів, форматованих як рядок (докладний опис рядків підпису D-Bus наведено у розділі системи типів специфікації D-Bus[2]). Для простих типів кожен параметр після підпису має бути простим значенням параметра, форматованого як рядок. Позитивні булеві значення може бути форматовано як "true", "yes", "on" або "1"; негативні булеві значення можна вказати як "false", "no", "off" або "0". Для масивів за числовим аргументом для кількості записів має бути вказано записи. Для варіантів має бути вказано підпис даних, а потім дані. Для словників і структур має бути безпосередньо вказано їхній вміст.

Приклад:

s jawoll

є форматуванням одного рядка "jawoll".

as 3 hello world foobar

є форматуванням масиву рядків із трьома записами, "hello", "world" і "foobar".

a{sv} 3 One s Eins Two u 2 Yes b true

є форматуванням масиву словника, який пов'язує рядки з варіантами і складається з трьох записів. Рядок "One" пов'язано із рядком "Eins". Рядок "Two" пов'язано із 32-бітовим цілим числом без знаку 2. Рядок "Yes" пов'язано із позитивним булевим значенням.

Зауважте, що команди call, get-property, introspect також виводять дані у цьому форматі. Оскільки цей формат є дещо складним для розуміння, команди call і get-property можуть виводити докладніші багаторядкові дані, якщо передано параметр --verbose.

ПРИКЛАДИ

Приклад 1. Записування і читання властивості

Наведені нижче дві команди спочатку записують значення властивості, а потім читають його. Властивість розташовано в об'єкті "/org/freedesktop/systemd1" служби "org.freedesktop.systemd1". Назвою властивості є "LogLevel" на інтерфейсі "org.freedesktop.systemd1.Manager". Властивість містить один рядок:

# busctl set-property org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager LogLevel s debug
# busctl get-property org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager LogLevel
s "debug"

Приклад 2. Скорочене і докладне виведення

Наступні дві команди читають властивість, яка містить масив рядків, і спершу виводять її у скороченому форматі, а потім у докладному:

$ busctl get-property org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager Environment
as 2 "LANG=en_US.UTF-8" "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin"
$ busctl get-property --verbose org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager Environment
ARRAY "s" {
        STRING "LANG=en_US.UTF-8";
        STRING "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin";
};

Приклад 3. Виклик методу

Наступна команда викликає метод "StartUnit" на інтерфейсі "org.freedesktop.systemd1.Manager" об'єкта "/org/freedesktop/systemd1" служби "org.freedesktop.systemd1" і передає йому два рядки, "cups.service" і "replace". Результатом виклику методу є отримання і показ одинарного параметра шляху до об'єкта:

# busctl call org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager StartUnit ss "cups.service" "replace"
o "/org/freedesktop/systemd1/job/42684"

ДИВ. ТАКОЖ

dbus-daemon(1), D-Bus[3], sd-bus(3), varlinkctl(1), systemd(1), machinectl(1), wireshark(1)

ПРИМІТКИ

1.: Формат файлів захоплених даних PCAP Next Generation (pcapng)

https://github.com/pcapng/pcapng/

2.: Глава щодо системи типів у специфікації D-Bus

https://dbus.freedesktop.org/doc/dbus-specification.html#type-system

3.: D-Bus

https://www.freedesktop.org/wiki/Software/dbus

ПЕРЕКЛАД

Український переклад цієї сторінки посібника виконано Yuri Chornoivan <yurchor@ukr.net>

Цей переклад є безкоштовною документацією; будь ласка, ознайомтеся з умовами GNU General Public License Version 3. НЕ НАДАЄТЬСЯ ЖОДНИХ ГАРАНТІЙ.

Якщо ви знайшли помилки у перекладі цієї сторінки підручника, будь ласка, надішліть електронний лист до списку листування перекладачів: trans-uk@lists.fedoraproject.org.

systemd 255