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
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
|
<refentry id="PolicyKit.conf.5">
<refentryinfo>
<title>PolicyKit.conf</title>
<date>August 2007</date>
<productname>PolicyKit</productname>
</refentryinfo>
<refmeta>
<refentrytitle>PolicyKit.conf</refentrytitle>
<manvolnum>5</manvolnum>
<refmiscinfo class="version"></refmiscinfo>
</refmeta>
<refnamediv>
<refname>PolicyKit.conf</refname>
<refpurpose>PolicyKit configuration file</refpurpose>
</refnamediv>
<refsect1><title>DESCRIPTION</title>
<para>
The <filename>/etc/PolicyKit/PolicyKit.conf</filename>
configuration file provides a way for system administrators to
override policy for mechanisms that use the PolicyKit library to
determine whether a caller is allowed to use the mechanism.
</para>
<para>
Changes to this configuration file are immediately propagated to
running processes using the PolicyKit library. If the
configuration file is invalid, processes using this library will
log this fact to the system logger and the library will only
only return <emphasis>no</emphasis> as the answer to processes
using it.
</para>
<para>
The <citerefentry><refentrytitle>polkit-config-file-validate</refentrytitle><manvolnum>1</manvolnum></citerefentry>
tool can be used to verify that the configuration file is
valid.
</para>
</refsect1>
<refsect1>
<title>FILE FORMAT</title>
<para>
The configuration file is an XML document. It must have the
following doctype declaration:
</para>
<programlisting>
<![CDATA[
<!DOCTYPE pkconfig PUBLIC
"-//freedesktop//DTD PolicyKit Configuration 1.0//EN"
"http://hal.freedesktop.org/releases/PolicyKit/1.0/config.dtd">
]]>
</programlisting>
<para>
The following elements may be present in the configuration file:
</para>
<refsect2>
<title>config</title>
<para>
This is the root element. A single
attribute <emphasis>version</emphasis> must be present and
must be set to "0.1" at this point. There can only be one
<emphasis>config</emphasis> element in the configuration file.
</para>
</refsect2>
<refsect2>
<title>match</title>
<para>
This element is for matching information related to the
decision making process and includes values describing both
the caller and the action. This element can be embedded in
both <emphasis>config</emphasis> and
other <emphasis>match</emphasis> elements (hence allowing for
nested matching).
</para>
<para>
There can only be a single attribute in
each <emphasis>match</emphasis> element and POSIX Extended
Regular Expression syntax are supported in the value part. The
following attributes are supported:
</para>
<variablelist>
<varlistentry>
<term><emphasis>user</emphasis></term>
<listitem>
<para>
This matches on the users login name.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis>action</emphasis></term>
<listitem>
<para>
For matching on the given action being queried for, for
example
<emphasis>action="org.foo.*"</emphasis> will match
on all actions whose action identifier begins with
the string "org.foo.".
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect2>
<refsect2>
<title>return</title>
<para>
This element is for used to specify what result the PolicyKit
library will return. It can only be embedded in
<emphasis>config</emphasis> and <emphasis>match</emphasis>
elements and can embed no elements
itself. The <emphasis>return</emphasis> element is
typically used deeply inside a number
of <emphasis>match</emphasis> elements. A single attribute,
<emphasis>result</emphasis> is supported and it can assume
the following values:
</para>
<variablelist>
<varlistentry>
<term><emphasis>no</emphasis></term>
<listitem>
<para>
Access denied.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis>auth_self</emphasis></term>
<listitem>
<para>
Access denied, but authentication of the caller as
himself will grant access to only that caller.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis>auth_self_keep_session</emphasis></term>
<listitem>
<para>
Access denied, but authentication of the caller as
himself will grant access to any caller in the
session of the caller belongs to.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis>auth_self_keep_always</emphasis></term>
<listitem>
<para>
Access denied, but authentication of the caller as
himself will grant access any caller with the given
uid in the future.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis>auth_admin</emphasis></term>
<listitem>
<para>
Access denied, but authentication of the caller as
an administrative user will grant access to only
that caller.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis>auth_admin_keep_session</emphasis></term>
<listitem>
<para>
Access denied, but authentication of the caller as
an administrative user will grant access to any caller
in the session of the caller belongs to.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis>auth_admin_keep_always</emphasis></term>
<listitem>
<para>
Access denied, but authentication of the caller as
an administrative user will grant access any caller
with the given uid in the future.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis>yes</emphasis></term>
<listitem>
<para>
Access granted.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect2>
<refsect2>
<title>define_admin_auth</title>
<para>
This element is used to specify the meaning of
<emphasis>"authenticate as administrator"</emphasis>. It
is normally used at the top-level but can also be used
deep inside a number of
<emphasis>match</emphasis> elements for conditional
behavior.
</para>
<para>
There can only be a single attribute in
each <emphasis>define_admin_auth</emphasis> element. POSIX
Extended Regular Expression syntax
is <emphasis>not</emphasis> supported in the value part,
however multiple values to match on can be separated with
the bar (|) character. The following attributes are
supported:
</para>
<variablelist>
<varlistentry>
<term><emphasis>user</emphasis></term>
<listitem>
<para>
Administrator authentication means authenticate as
the given user(s). If
no <emphasis>define_admin_auth</emphasis> element is
given, the default is to
use <emphasis>user="root"</emphasis>
e.g. administrator authentication mean authenticate
as the super user.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis>group</emphasis></term>
<listitem>
<para>
Administrator authentication means that any user in
the groups matching the given value can be used to
authenticate. Typically, on a system with the root
account disabled one wants to use something like
<emphasis>group="wheel"</emphasis> to e.g. enable
all UNIX users in the UNIX group
<emphasis>wheel</emphasis> to be able to
authentication whenever administrator authentication
is required.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect2>
</refsect1>
<refsect1>
<title>EXAMPLES</title>
<para>
For brevity, the standard XML and DOCTYPE headers as well as
the top-level <emphasis>config</emphasis> are omitted in the
following configuration file examples. The actions used may
also be fictional,
use <citerefentry><refentrytitle>polkit-action</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
to learn about the actions available on your system.
</para>
<refsect2>
<title>ALLOW EVERYTHING</title>
<para>
The users "davidz" and "bateman" are allowed to do any
action:
</para>
<programlisting>
<![CDATA[
<match user="davidz|bateman">
<return result="yes"/>
</match>
]]>
</programlisting>
</refsect2>
<refsect2>
<title>MOUNTING FIXED DRIVES</title>
<para>
Suppose the
action <emphasis>org.freedesktop.hal.storage.mount-fixed</emphasis>
is used to determine whether mounting internal hard drives
are allowed. Then this configuration file
</para>
<programlisting>
<![CDATA[
<match action="org.freedesktop.hal.storage.mount-fixed">
<match user="davidz">
<return result="yes"/>
</match>
<match user="freddy">
<return result="no"/>
</match>
</match>
]]>
</programlisting>
<para>
specifies that user "davidz" is always allowed to do the
action, while user "freddy" is never allowed to do the
action. Other users will be subject to the defaults
results specified in the <emphasis>.policy</emphasis> file
describing the action.
</para>
</refsect2>
<refsect2>
<title>AVOIDING THE ROOT PASSWORD</title>
<para>
Suppose the group <emphasis>wheel</emphasis> contains the
users on a system who are allowed to carry out administrative
tasks (ie. tasks that would usually require the root password)
on a system where the root account is disabled. Then
</para>
<programlisting>
<![CDATA[
<define_admin_auth group="wheel"/>
]]>
</programlisting>
<para>
can be used to specify that users in said group can
authenticate using their own password in instances where the
system would normally prompt for the root password.
</para>
</refsect2>
</refsect1>
<refsect1>
<title>AUTHOR</title>
<para>
Written by David Zeuthen <email>david@fubar.dk</email> with
a lot of help from many others.
</para>
</refsect1>
<refsect1>
<title>BUGS</title>
<para>
Please send bug reports to either the distribution or the
hal mailing list,
see <ulink url="http://lists.freedesktop.org/mailman/listinfo/hal"/>.
to subscribe.
</para>
</refsect1>
<refsect1>
<title>SEE ALSO</title>
<para>
<citerefentry>
<refentrytitle>PolicyKit</refentrytitle><manvolnum>8</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>polkit-config-file-validate</refentrytitle><manvolnum>1</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>polkit-action</refentrytitle><manvolnum>1</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>polkit-auth</refentrytitle><manvolnum>1</manvolnum>
</citerefentry>
</para>
</refsect1>
</refentry>
|
