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
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
|
<?xml version='1.0'?> <!--*-nxml-*-->
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<refentry id="kdbus.endpoint">
<refentryinfo>
<title>kdbus.endpoint</title>
<productname>kdbus.endpoint</productname>
</refentryinfo>
<refmeta>
<refentrytitle>kdbus.endpoint</refentrytitle>
<manvolnum>7</manvolnum>
</refmeta>
<refnamediv>
<refname>kdbus.endpoint</refname>
<refpurpose>kdbus endpoint</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<para>
Endpoints are entry points to a bus (see
<citerefentry><refentrytitle>kdbus.bus</refentrytitle><manvolnum>7</manvolnum></citerefentry>).
By default, each bus has a default
endpoint called 'bus'. The bus owner has the ability to create custom
endpoints with specific names, permissions, and policy databases (see below).
An endpoint is presented as file underneath the directory of the parent bus.
</para>
<para>
To create a custom endpoint, open the default endpoint ('bus') and use the
KDBUS_CMD_ENDPOINT_MAKE ioctl with "struct kdbus_cmd_make". Custom endpoints
always have a policy database that, by default, forbids any operation. You have
to explicitly install policy entries to allow any operation on this endpoint.
</para>
<para>
Once KDBUS_CMD_ENDPOINT_MAKE succeeded, the new endpoint will appear in the
filesystem
(<citerefentry><refentrytitle>kdbus.bus</refentrytitle><manvolnum>7</manvolnum></citerefentry>),
and the used file descriptor will manage the
newly created endpoint resource. It cannot be used to manage further resources
and must be kept open as long as the endpoint is needed. The endpoint will be
terminated as soon as the file descriptor is closed.
</para>
<para>
Endpoint names may be chosen freely except for one restriction: the name must
be prefixed with the numeric effective UID of the creator and a dash. This is
required to avoid namespace clashes between different users. When creating an
endpoint, the name that is passed in must be properly formatted or the kernel
will refuse creation of the endpoint. Example: "1047-foobar" is an acceptable
name for an endpoint registered by a user with UID 1047. However,
"1024-my-endpoint" is not, and neither is "my-endpoint". The UID must be
provided in the user-namespace of the parent domain.
</para>
<para>
To create connections to a bus, use KDBUS_CMD_HELLO on a file descriptor returned by
<citerefentry><refentrytitle>open</refentrytitle><manvolnum>2</manvolnum></citerefentry>
on an endpoint node.
See <citerefentry><refentrytitle>kdbus.connection</refentrytitle><manvolnum>7</manvolnum></citerefentry>
for further details.
</para>
</refsect1>
<refsect1>
<title>Creating custom endpoints</title>
<para>
To create a new endpoint, the <varname>KDBUS_CMD_ENDPOINT_MAKE</varname>
command is used. Along with the endpoint's name, which will be used to
expose the endpoint in the
<citerefentry><refentrytitle>kdbus.fs</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
the command also optionally takes items to set up the endpoint's
<citerefentry><refentrytitle>kdbus.policy</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
<varname>KDBUS_CMD_ENDPOINT_MAKE</varname> takes a
<varname>struct kdbus_cmd_make</varname> argument.
</para>
<programlisting>
struct kdbus_cmd_make {
__u64 size;
__u64 flags;
__u64 kernel_flags;
__u64 return_flags;
struct kdbus_item items[0];
};
</programlisting>
<para>The fields in this struct are described below.</para>
<variablelist>
<varlistentry>
<term><varname>size</varname></term>
<listitem><para>
The overall size of the struct, including its items.
</para></listitem>
</varlistentry>
<varlistentry>
<term><varname>flags</varname></term>
<listitem><para>The flags for creation.</para>
<variablelist>
<varlistentry>
<term><varname>KDBUS_MAKE_ACCESS_GROUP</varname></term>
<listitem>
<para>Make the endpoint file group-accessible</para>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>KDBUS_MAKE_ACCESS_WORLD</varname></term>
<listitem>
<para>Make the endpoint file world-accessible</para>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>kernel_flags</varname></term>
<listitem><para>
Valid flags for this command, returned by the kernel upon each call.
</para></listitem>
</varlistentry>
<varlistentry>
<term><varname>return_flags</varname></term>
<listitem><para>
Flags returned by the kernel. Currently unused and always set to
zero by the kernel.
</para></listitem>
</varlistentry>
<varlistentry>
<term><varname>items</varname></term>
<listitem>
<para>
The following items are expected for
<varname>KDBUS_CMD_ENDPOINT_MAKE</varname>.
</para>
<variablelist>
<varlistentry>
<term><varname>KDBUS_ITEM_MAKE_NAME</varname></term>
<listitem>
<para>Contains a string to identify the endpoint name.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>KDBUS_ITEM_NAME</varname></term>
<term><varname>KDBUS_ITEM_POLICY_ACCESS</varname></term>
<listitem>
<para>
These items are used to set the policy attached to the
endpoint. For more details on bus and endpoint policies, see
<citerefentry><refentrytitle>kdbus.policy</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
Unrecognized items are rejected, and the ioctl will fail with
<varname>-EINVAL</varname>.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Updating endpoints</title>
<para>
To update an existing endpoint, the
<varname>KDBUS_CMD_ENDPOINT_UPDATE</varname> command is used on the file
descriptor that was used to create the update, using
<varname>KDBUS_CMD_ENDPOINT_MAKE</varname>. The only relevant detail of
the endpoint that can be updated is the policy. When the command is
employed, the policy of the endpoint is <emphasis>replaced</emphasis>
atomically with the new set of rules.
The command takes a <varname>struct kdbus_cmd_update</varname> argument.
</para>
<programlisting>
struct kdbus_cmd_make {
__u64 size;
__u64 flags;
__u64 kernel_flags;
__u64 return_flags;
struct kdbus_item items[0];
};
</programlisting>
<para>The fields in this struct are described below.</para>
<variablelist>
<varlistentry>
<term><varname>size</varname></term>
<listitem><para>
The overall size of the struct, including its items.
</para></listitem>
</varlistentry>
<varlistentry>
<term><varname>flags</varname></term>
<listitem><para>
Unused for this command.
</para></listitem>
</varlistentry>
<varlistentry>
<term><varname>kernel_flags</varname></term>
<listitem><para>
Valid flags for this command, returned by the kernel upon each call.
</para></listitem>
</varlistentry>
<varlistentry>
<term><varname>return_flags</varname></term>
<listitem><para>
Flags returned by the kernel. Currently unused and always set to
zero by the kernel.
</para></listitem>
</varlistentry>
<varlistentry>
<term><varname>items</varname></term>
<listitem>
<para>
The following items are expected for
<varname>KDBUS_CMD_ENDPOINT_UPDATE</varname>.
</para>
<variablelist>
<varlistentry>
<term><varname>KDBUS_ITEM_NAME</varname></term>
<term><varname>KDBUS_ITEM_POLICY_ACCESS</varname></term>
<listitem>
<para>
These items are used to set the policy attached to the
endpoint. For more details on bus and endpoint policies, see
<citerefentry><refentrytitle>kdbus.policy</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
Existing policy is atomically replaced with the new rules
provided.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
Unrecognized items are rejected, and the ioctl will fail with
<varname>-EINVAL</varname>.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Return value</title>
<para>
On success, all mentioned ioctl commands return 0.
</para>
<para>
<varname>KDBUS_CMD_ENDPOINT_MAKE</varname> may return the following errors.
</para>
<variablelist>
<varlistentry>
<term><varname>-EINVAL</varname></term>
<listitem><para>
The flags supplied in the <varname>struct kdbus_cmd_make</varname>
are invalid.
</para></listitem>
</varlistentry>
<varlistentry>
<term><varname>-EEXIST</varname></term>
<listitem><para>
An endpoint of that name already exists.
</para></listitem>
</varlistentry>
<varlistentry>
<term><varname>-EPERM</varname></term>
<listitem><para>
The calling user is not privileged. See
<citerefentry><refentrytitle>kdbus</refentrytitle><manvolnum>7</manvolnum></citerefentry>
for information about privileged users.
</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>See Also</title>
<simplelist type="inline">
<member><citerefentry><refentrytitle>kdbus</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>kdbus.bus</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>kdbus.endpoint</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>kdbus.fs</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>kdbus.item</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>kdbus.message</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>kdbus.names</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>kdbus.pool</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
</simplelist>
</refsect1>
</refentry>
|
