-
Notifications
You must be signed in to change notification settings - Fork 0
/
specification.txt
218 lines (155 loc) · 6.97 KB
/
specification.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
The Unix Stream Bus
Antidesktop.org standards group. Standard Nr. 2
DRAFT 29/4/2011
0. References
[ADO RMI] http://antidesktop.org/std/ado-1-rsi.txt
1. Motivation
System V IPC mechanisms offer no utils for situations
where multiple processes shall be connected.
Typical applications are system/session daemons which
can be accessed by multiple other processes.
Those applications either have to provide their own
mechanism, or use dbus.
Ubus provides such functionality without the need for
a system daemon. Its implementation is meant to be simple.
A ubus implementation can easily be written in pure shell
(if the shell supports sockets).
Ubus establishes bidirectional multicast pipes. While
they can be used for any purpose, this specification
also provides a standard protocol for RMI.
2. Bus
A bus is a unix domain socket (AF_UNIX and SOCK_STREAM)
located in:
/var/ubus/application_name/
or
~/.ubus/application_name/
depending on, if the owner is a system or session service.
3. Services
Services are applications providing one or multiple buses.
They create the socket in the appropriate directory, listen
for incoming requests, and destroy the bus when they see fit.
Applications MUST delete the bus on exit, even when exiting
due to a signal.
The on disk layout of buses SHOULD reflect the logical object
layout of the application. The applications ipc directory
may contain sub-directories.
4. Connections
A connection is a bidirectional pipe established with a bus.
An application may establish a connection with a bus, by
simply connecting to the file via connect (3).
5. Communication types
5.1 Signals
A signal is a bus, where each connection receives
a call when a specific event in the service happened.
Calls sent towards the service are either ignored,
or not synchronized.
Signals carry the file ending ".signal".
5.2 Methods
On a method connection, a call is sent to the
service, then the service responds with the
return value. Each request MUST be followed by a
response, in the same order they were sent.
Methods carry the file ending ".method".
5.3 Properties
Upon connection, the service immediately sends the
current value to the client. A client may then send
a new value. If the new value is accepted, it is
again written to all connections. If it is rejected
an error (bell) COULD BE sent and the connection is
terminated.
Properties carry the file ending ".property".
5.4 Restful bus
A client first sends a request, then closes the write
channel. The service sends a response, and closes the
read channel. Both request and response may be
arbitrary binary code or even empty.
Error handling must be implemented at application
level.
Rest buses carry the file ending ".rest".
6 Call Format
The format of signals, methods, and properties shall
be [ADO RMI] as defined by the antidesktop.org
standards group ADO STD Nr 1.
7. Bus discovery and recovery
Applications may establish connections to services that
are not started yet. Implementations SHOULD use inotify
or other available utils to monitor the path for creation
of the file.
If a socket is a zombie, implementations SHOULD attemp to
reconnect when the file is recreated. Implementations
MUST handle unexpected disconnect gracefully. They SHOULD
provide an option for automatic reconnection.
8. Security
Standard unix file permissions are used to prevent discoery
from unauthorized users. Access rights SHOULD NOT change
during operation.
Service implementations MUST be prepared to handle connections
from unauthorized users, as some Operating systems ignore
permissions on named pipes.
Client implementations MUST fail immediately to connect to a
socket without required permissions (as opposed to trying until
success )
9. Scripting interface
Binaries are provided that help in scripting and remoting.
If a path to a bus does not begin with "/" or "./" ,
it is relative to ~/.ipc/.
9.1 "ubus"
The "ubus" binary allocates channels and maintains
connections.
Messages from connections are written to stdout,
prefixed with an identifier for the bus and the client.
They are rewritten as
command\tbus\tclient\tactualmessage\n,
so that the ids are actually rmi arguments.
for the sake of readability, all \t are shown here
as space again.
Commands via stdin:
b 4 app/fish.signal : create a new bus app/fish.signal
and identify it with "4"
u 4 : destroy bus 4
w 4 123 ... : message client 123 on bus 4
d 4 123 : disconnect client 123 on bus 4
On stdout you get:
b 4 1 : bus 4 created
b 4 0 123 dummy : bus 4 not created because of
error 123 "dummy"
c 4 123 : client 123 connected
r 4 123 ... : message from client 123
d 4 123 : client 123 disconnected
The identifier is arbitrary text, and can be reused for
a new client, after an old one disconnected.
A * can be used as client identifier to mean all
connected clients, ie broadcast. A * in the bus identifier
has no meaning, and is part of the name.
Lines beginning with an unknown command, MUST be ignored.
Commandline arguments are interpreted as buses to open.
Ie, ubus foo/bla bar/baz will open two channels and give
them the idents 1 and 2.
Client connections to existing buses are also possible:
k 5 app/fish.signal : connect to bus app/fish.signal
i 5 : disconnect
On stdout:
k 5 1 : bus 4 connected
k 5 0 123 dummy : bus 4 not connected because of
error 123 "dummy"
Read/writes are the same as with buses you created. The
client identifier must then always be empty.
9.3 "ubus-signal"
Creates one bus given as command line argument.
Does not prefix any message. Stdin is broadcasted,
Stdout shows all data from all clients, interleaved.
Can be used for properties as well.
9.4 "ubus-connect"
connects to one bus given as command line argument.
stdin/stdout are wired to the bus.
Identical to "socat STDIO UNIX-CONNECT:/path/to/bus", except
that it is safe to assume its existence.
10. Buses on remote machines
10.1 ssh
Applications can create and connect to buses on remote
machines, via ssh. For that to work, the remote machine
must have the scripting interface installed.
An implementation can just call
"ssh host ubus"
10.2 tcp
TODO: inetd? whats with encryption? do we even care?