Mercurial > libervia-backend

comparison doc/libervia-cli/ad-hoc.rst @ 3488:c80a0f864b5d

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc: updated doc following global renaming
author Goffi <goffi@goffi.org>
date Sun, 21 Mar 2021 18:23:58 +0100
parents doc/jp/ad-hoc.rst@72583524cfd3
children 267e4987b58b
comparison
equal deleted inserted replaced
3487:75427f0a5445 3488:c80a0f864b5d
1 =======================
2 ad-hoc: Ad-Hoc commands
3 =======================
4
5 Ad-Hoc commands is a generic mechanism of XMPP to control an entity. They can be used
6 either by humans, or automated. Ad-Hoc commands can be used for administration (e.g. get
7 list of connected users, send a service announcement, restart parts of the server), or
8 execute about anything (e.g. control a physical robot with XMPP).
9
10 run
11 ===
12
13 Run an ad-hoc command. You may specify the node to run as positional argument, or let it
14 empty to list available commands.
15
16 By default the commands from your server are used, but with ``-j JID, --jid JID`` you can
17 specify a different entity.
18
19 You can automatically execute commands by using ``-f KEY VALUE, --field KEY VALUE`` and
20 ``-S, --submit`` as many time as needed. ``--field`` expect a ``KEY`` which is the name
21 of the field to set. If you don't know which name to use, you can run the command to
22 automatise a first time manually with ``--verbose, -v`` flag, this will display fields
23 names when you have to fill them.
24
25 Once all fields of a page are specified, you may use ``-S, --submit`` to validate it, then
26 if suitable use again ``--field`` to set fields of next page and ``--submit`` again, and
27 so on as many times as you need.
28
29 Don't forget that you can use your shell substitution capabilities if necessary, for
30 instance if you have a pre-registered announce to send.
31
32 examples
33 --------
34
35 Get a list of available commands on your server to launch a command::
36
37 $ li ad-hoc run
38
39 If your server supports `XEP-0133`_ and you're an admin on it, you can send announcements
40 to online users. This can be useful to notify an imminent maintenance of the server. Here
41 we notify online users that the server will be shutdown in 30 min, using a shell
42 substitution capabilities with a pre-registered message in the file
43 ``~/announces/maintenance_30.txt``, then we submit it::
44
45 $ li ad-hoc run "http://jabber.org/protocol/admin#announce" -f subject "Maintenance in 30 min" -f announcement "$(<~/announces/maintenance_30.txt)" -S
46
47 Get your server uptime (if supported by your server)::
48
49 $ li ad-hoc run uptime
50
51 Run the commands available at the service with the jid ``someservice.example.org``::
52
53 $ li ad-hoc run -s someservice.example.org
54
55 Run you server commands with verbosity so you get the name of the fields that you can fill
56 automatically later::
57
58 $ li ad-hoc run -v
59
60 .. _XEP-0133: https://xmpp.org/extensions/xep-0133.html
61
62 list
63 ====
64
65 List ad-hoc commands available at a service.
66
67 examples
68 --------
69
70 List ad-hoc commands available at your server::
71
72 $ li ad-hoc list
73
74 List ad-hoc commands available at a chat service::
75
76 $ li ad-hoc list -j conference.example.org
77
78 remote
79 ======
80
81 Create a remote control from launched media players. Ad-hoc commands to control the media
82 player will be added to your device, allowing anybody allowed (including yourself from an
83 other device, e.g. a phone) to remotely do action like ``play``, ``pause``, etc.
84
85 To add a device, just use the name of the software (e.g. ``vlc``, ``smplayer``). You can
86 specify who is allowed to control this media player with the following options:
87
88 ``-j [JIDS [JIDS ...]], --jids [JIDS [JIDS ...]]``
89 jids of entities allowed to control the media player
90
91 ``g [GROUPS [GROUPS ...]], --groups [GROUPS [GROUPS ...]]``
92 groups (from your roster) allowed to control you remote
93
94 ``--forbidden-groups [FORBIDDEN_GROUPS [FORBIDDEN_GROUPS ...]]``
95 groups (from your roster) which are **NOT** allowed to control your media player
96
97 ``--forbidden-jids [FORBIDDEN_JIDS [FORBIDDEN_JIDS ...]]``
98 jids of entities which are **NOT** allowed to control your media player
99
100 If you want the commands to run repeatedly (in opposition of stopping after first action
101 is sent), you may use the ``-l, --loop`` option. Most of time you'll want to use it.
102
103 .. note::
104
105 SàT already creates automatically a remote control if it finds a media player. This
106 manual way to create a remote control predate the automatic remote control, and is
107 currently more flexible in that you can specify who can access the remote control
108 (automatic remote control is only accessible by the jid of the profile).
109
110 examples
111 --------
112
113 Create a remote control for a running VLC instance::
114
115 $ li ad-hoc remote vlc -l
116
117 Create a remote control for a running SMPlayer instance, and allowing anybody from your
118 ``housemates`` group to use it::
119
120 $ li ad-hoc remote smplayer -g housemates -l