busctl - introspecter et surveiller le bus D-Bus
busctl [OPTIONS...] [COMMAND] [NAME...]
busctl peut être utilisé pour inspecter et surveiller le bus D-Bus.
Les commandes suivantes sont comprises :
Afficher tous les pairs sur le bus, par leurs noms de service. Par défaut, affiche les noms uniques et connus, mais cela peut être modifié avec les commutateurs --unique et --acquired. Il s'agit de l'opération par défaut si aucune commande n'est spécifiée.
Afficher les informations de processus et les informations d'identification d'un service de bus (si l'un est spécifié par son nom unique ou bien connu), un processus (si l'un est spécifié par son PID numérique) ou le propriétaire du bus (si aucun paramètre n'est spécifié) .
Vider les messages en cours d'échange. Si SERVICE est spécifié, affiche les messages vers ou depuis ce pair, identifié par son nom connu ou unique. Sinon, affichez tous les messages sur le bus. Utilisez Ctrl+C pour terminer le vidage.
Semblable à monitor mais écrit la sortie au format pcapng (pour plus de détails, voir PCAP Next Generation (pcapng) Capture File Format[1]). Assurez-vous de rediriger la sortie standard vers un fichier ou un tube. Des outils comme wireshark(1) peuvent être utilisés pour disséquer et visualiser les fichiers résultants.
Affiche une arborescence d'objets d'un ou plusieurs services. Si SERVICE est spécifié, affiche l'arborescence d'objets des services spécifiés uniquement. Sinon, affichez toutes les arborescences d'objets de tous les services sur le bus qui ont acquis au moins un nom connu.
Affiche les interfaces, les méthodes, les propriétés et les signaux de l'objet spécifié (identifié par son chemin) sur le service spécifié. Si l'argument interface est passé, la sortie est limitée aux membres de l'interface spécifiée.
Appelez une méthode et affichez la réponse. Prend un nom de service, un chemin d'objet, un nom d'interface et un nom de méthode. Si des paramètres doivent être transmis à l'appel de méthode, une chaîne de signature est requise, suivie des arguments, formatés individuellement en tant que chaînes. Pour plus de détails sur le formatage utilisé, voir ci-dessous. Pour supprimer la sortie des données renvoyées, utilisez l'option --quiet.
Émettre un signal. Prend un chemin d'objet, un nom d'interface et un nom de méthode. Si des paramètres doivent être passés, une chaîne de signature est requise, suivie des arguments, formatés individuellement en tant que chaînes. Pour plus de détails sur le formatage utilisé, voir ci-dessous. Pour spécifier la destination du signal, utilisez l'option --destination=.
Récupère la valeur actuelle d'une ou plusieurs propriétés d'objet. Prend un nom de service, un chemin d'objet, un nom d'interface et un nom de propriété. Plusieurs propriétés peuvent être spécifiées à la fois, auquel cas leurs valeurs seront affichées les unes après les autres, séparées par des retours à la ligne. La sortie est, par défaut, au format laconique. Utilisez --verbose pour un format de sortie plus élaboré.
Définissez la valeur actuelle d'une propriété d'objet. Prend un nom de service, un chemin d'objet, un nom d'interface, un nom de propriété, une signature de propriété, suivis d'une liste de paramètres formatés en tant que chaînes.
Afficher l'aide sur la syntaxe de la commande.
Les options suivantes sont comprises :
Connectez-vous au bus spécifié par ADDRESS au lieu d'utiliser les valeurs par défaut appropriées pour le système ou le bus utilisateur (voir les options --system et --user ).
Lorsque vous affichez la liste des pairs, affichez une colonne contenant les noms des conteneurs auxquels ils appartiennent. Voir systemd-machined.service(8).
Lors de l'affichage de la liste des pairs, n'afficher que les noms "uniques" (de la forme ":numéro.numéro").
Le contraire de --unique — seuls les noms "connus" seront affichés.
Lors de l'affichage de la liste des pairs, affichez uniquement les pairs qui n'ont pas encore été activés, mais qui peuvent être démarrés automatiquement en cas d'accès.
Lorsque vous affichez les messages en cours d'échange, affichez uniquement le sous-ensemble correspondant à MATCH. Voir sd_bus_add_match(3).
Lorsqu'il est utilisé avec la commande capture, spécifie la taille maximale du message de bus à capturer ("snaplen"). La valeur par défaut est 4096 octets.
Lorsqu'il est utilisé avec la commande tree, affiche une liste plate de chemins d'objets au lieu d'un arbre.
Lorsqu'il est utilisé avec la commande call, supprime l'affichage de la charge utile du message de réponse. Notez que même si cette option est spécifiée, les erreurs renvoyées seront toujours imprimées et l'outil indiquera la réussite ou l'échec avec le code de sortie du processus.
Lorsqu'il est utilisé avec la commande call ou get-property, affiche la sortie dans un format plus détaillé.
Lorsqu'il est utilisé avec l'appel introspect, vide la description XML reçue de l'appel D-Bus org.freedesktop.DBus.Introspectable.Introspect au lieu de la sortie normale.
Lorsqu'il est utilisé avec la commande call ou get-property, affiche la sortie au format JSON. Attend l'un de "court" (pour la sortie la plus courte possible sans aucun espace blanc ni saut de ligne redondant) ou "joli" (pour une jolie version de la même chose, avec indentation et sauts de ligne). Notez que la transformation du marshaling D-Bus en JSON s'effectue sans perte, ce qui signifie que les informations de type sont intégrées dans l'arborescence d'objets JSON.
Équivalent à --json=pretty lorsqu'il est appelé de manière interactive à partir d'un terminal. Autrement équivalent à --json=short, en particulier lorsque la sortie est redirigée vers un autre programme.
Lorsqu'il est utilisé avec la commande call, spécifie si busctl doit attendre la fin de l'appel de la méthode, afficher les données de réponse de la méthode renvoyées et renvoyer le succès ou l'échec via le code de sortie du processus . S'il est défini sur "non", l'appel de méthode sera émis mais aucune réponse n'est attendue, l'outil se termine immédiatement, et donc aucune réponse ne peut être affichée, et aucun succès ou échec n'est renvoyé via le code de sortie. Pour supprimer uniquement la sortie de la charge utile du message de réponse, utilisez --quiet ci-dessus. La valeur par défaut est "oui".
Lorsqu'il est utilisé avec la commande call ou emit, spécifie si l'appel de méthode doit implicitement activer le service appelé, s'il n'est pas encore en cours d'exécution mais est configuré pour être démarré automatiquement. La valeur par défaut est "oui".
Lorsqu'il est utilisé avec la commande call, spécifie si les services peuvent appliquer une autorisation interactive lors de l'exécution de l'opération, si la politique de sécurité est configurée pour cela. La valeur par défaut est "oui".
Lorsqu'il est utilisé avec la commande call, spécifie le temps maximum d'attente pour l'achèvement de l'appel de méthode. Si aucune unité de temps n'est spécifiée, suppose des secondes. Les autres unités habituelles sont également comprises (ms, us, s, min, h, d, w, month, y). Notez que ce délai ne s'applique pas si --expect-reply=no est utilisé, car l'outil n'attend alors aucun message de réponse. Lorsqu'il n'est pas spécifié ou lorsqu'il est défini sur 0, la valeur par défaut de "25 s" est utilisée.
Contrôle si les données d'identification signalées par list ou status doivent être complétées par les données de /proc/. Lorsque cette option est activée, les données affichées sont peut-être incohérentes, car les données lues à partir de /proc/ peuvent être plus récentes que le reste des informations d'identification. La valeur par défaut est "oui".
Contrôle s'il faut attendre que le socket de bus AF_UNIX spécifié apparaisse dans le système de fichiers avant de s'y connecter. Désactivé par défaut. Lorsqu'il est activé, l'outil surveillera le système de fichiers jusqu'à ce que le socket soit créé, puis s'y connectera.
Prend un nom de service. Lorsqu'il est utilisé avec la commande emit, un signal est émis vers le service spécifié.
Parlez au gestionnaire de service de l'utilisateur appelant, plutôt qu'au gestionnaire de service du système.
Parlez au gestionnaire de service du système. Il s'agit de la valeur par défaut implicite.
Exécutez l'opération à distance. Spécifiez un nom d'hôte, ou un nom d'utilisateur et un nom d'hôte séparés par "@", pour vous connecter. Le nom d'hôte peut éventuellement être suffixé par un port sur lequel ssh écoute, séparé par ":", puis un nom de conteneur, séparé par "/", qui se connecte directement à un conteneur spécifique sur l'hôte spécifié. Cela utilisera SSH pour parler à l'instance distante du gestionnaire de machines. Les noms de conteneurs peuvent être énumérés avec machinectl -H HOST. Mettez les adresses IPv6 entre parenthèses.
Exécutez l'opération sur un conteneur local. Spécifiez un nom de conteneur auquel se connecter, éventuellement préfixé par un nom d'utilisateur pour se connecter en tant que et un caractère "@" de séparation. Si la chaîne spéciale ".host" est utilisée à la place du nom du conteneur, une connexion au système local est établie (ce qui est utile pour se connecter au bus utilisateur d'un utilisateur spécifique : "--user --machine=lennart@.host "). Si la syntaxe "@" n'est pas utilisée, la connexion est établie en tant qu'utilisateur root. Si la syntaxe "@" est utilisée, le côté gauche ou le côté droit peut être omis (mais pas les deux), auquel cas le nom d'utilisateur local et ".host" sont implicites.
N'ellipsez pas la sortie dans la commande list.
Ne dirigez pas la sortie vers un téléavertisseur.
N'imprimez pas la légende, c'est-à-dire les en-têtes de colonne et le pied de page avec des conseils.
Imprimez un court texte d'aide et quittez.
Imprimez une chaîne de version courte et quittez.
Les commandes call et set-property prennent une chaîne de signature suivie d'une liste de paramètres formatés en tant que chaîne (pour plus de détails sur les chaînes de signature D-Bus, consultez la section Type chapitre système de la spécification D-Bus[2]). Pour les types simples, chaque paramètre suivant la signature doit simplement être la valeur du paramètre formatée en chaîne. Les valeurs booléennes positives peuvent être formatées comme "true", "yes", "on" ou "1" ; les valeurs booléennes négatives peuvent être spécifiées comme "false", "no", "off" ou "0". Pour les tableaux, un argument numérique pour le nombre d'entrées suivi des entrées doit être spécifié. Pour les variantes, la signature du contenu doit être précisée, suivie du contenu. Pour les dictionnaires et les structures, leur contenu doit être directement spécifié.
Par exemple,
s jawoll
est le formatage d'une seule chaîne "jawoll".
as 3 hello world foobar
est le formatage d'un tableau de chaînes avec trois entrées, "hello", "world" et "foobar".
a{sv} 3 One s Eins Two u 2 Yes b true
est la mise en forme d'un tableau de dictionnaire qui mappe des chaînes à des variantes, composé de trois entrées. La chaîne "One" est affectée de la chaîne "Eins". La chaîne "Deux" est affectée de l'entier non signé 32 bits 2. La chaîne "Oui" est affectée d'un booléen positif.
Notez que les commandes call, get-property, introspect généreront également une sortie dans ce format pour les données renvoyées. Étant donné que ce format est parfois trop concis pour être facilement compris, les commandes call et get-property peuvent générer une sortie multiligne plus détaillée lorsqu'elles sont passées à la - -option détaillée.
Exemple 1. Écrire et lire une propriété
Les deux commandes suivantes écrivent d'abord une propriété, puis la relisent. La propriété se trouve sur l'objet "/org/freedesktop/systemd1" du service "org.freedesktop.systemd1". Le nom de la propriété est "LogLevel" sur l'interface "org.freedesktop.systemd1.Manager". La propriété contient une seule chaîne :
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"
Exemple 2. Sortie concise et détaillée
Les deux commandes suivantes lisent une propriété qui contient un tableau de chaînes et l'affichent d'abord au format concis, suivi d'un format détaillé :
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"; };
Exemple 3. Invoquer une méthode
La commande suivante appelle la méthode "StartUnit" sur l'interface "org.freedesktop.systemd1.Manager" de l'objet "/org/freedesktop/systemd1" du service "org.freedesktop.systemd1", et lui passe deux chaînes "cups .service" et "remplacer". À la suite de l'appel de méthode, un seul paramètre de chemin d'objet est reçu et affiché :
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), systemd(1), machinectl(1), wireshark(1)
Format de fichier de capture PCAP Next Generation (pcapng): https://github.com/pcapng/pcapng/
Chapitre sur le système de type de la spécification D-Bus : https://dbus.freedesktop.org/doc/dbus-specification.html#type-system
D-Bus : https://www.freedesktop.org/wiki/Software/dbus