source: postlfs/security/polkit.xml@ b317cda

12.0 12.1 ken/TL2024 ken/tuningfonts lazarus plabs/newcss python3.11 rahul/power-profiles-daemon renodr/vulkan-addition trunk xry111/llvm18
Last change on this file since b317cda was b317cda, checked in by Xi Ruoyao <xry111@…>, 9 months ago

polkit: Expand and fix the command explanation for js102 sed

and demote duktape to recommended (but still keep it required internally
for jhalfs).

  • Property mode set to 100644
File size: 15.2 KB
Line 
1<?xml version="1.0" encoding="ISO-8859-1"?>
2<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3 "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
4 <!ENTITY % general-entities SYSTEM "../../general.ent">
5 %general-entities;
6
7 <!ENTITY polkit-download-http "https://gitlab.freedesktop.org/polkit/polkit/-/archive/&polkit-version;/polkit-&polkit-version;.tar.gz">
8 <!ENTITY polkit-download-ftp " ">
9 <!ENTITY polkit-md5sum "36540b837c588e1e77145523bb39f511">
10 <!ENTITY polkit-size "736 KB">
11 <!ENTITY polkit-buildsize "6.8 MB (with tests)">
12 <!ENTITY polkit-time "0.3 SBU (with tests, using parallelism=4)">
13]>
14
15<sect1 id="polkit" xreflabel="Polkit-&polkit-version;">
16 <?dbhtml filename="polkit.html"?>
17
18
19 <title>Polkit-&polkit-version;</title>
20
21 <indexterm zone="polkit">
22 <primary sortas="a-Polkit">Polkit</primary>
23 </indexterm>
24
25 <sect2 role="package">
26 <title>Introduction to Polkit</title>
27
28 <para>
29 <application>Polkit</application> is a toolkit for defining and handling
30 authorizations. It is used for allowing unprivileged processes to
31 communicate with privileged processes.
32 </para>
33
34 &lfs120_checked;
35
36 <bridgehead renderas="sect3">Package Information</bridgehead>
37 <itemizedlist spacing="compact">
38 <listitem>
39 <para>
40 Download (HTTP): <ulink url="&polkit-download-http;"/>
41 </para>
42 </listitem>
43 <listitem>
44 <para>
45 Download (FTP): <ulink url="&polkit-download-ftp;"/>
46 </para>
47 </listitem>
48 <listitem>
49 <para>
50 Download MD5 sum: &polkit-md5sum;
51 </para>
52 </listitem>
53 <listitem>
54 <para>
55 Download size: &polkit-size;
56 </para>
57 </listitem>
58 <listitem>
59 <para>
60 Estimated disk space required: &polkit-buildsize;
61 </para>
62 </listitem>
63 <listitem>
64 <para>
65 Estimated build time: &polkit-time;
66 </para>
67 </listitem>
68 </itemizedlist>
69
70<!--
71 <bridgehead renderas="sect3">Additional Downloads</bridgehead>
72 <itemizedlist spacing="compact">
73 <listitem>
74 <para>
75 Required patch:
76 <ulink url="&patch-root;/polkit-&polkit-version;-security_fixes-1.patch"/>
77 </para>
78 </listitem>
79 <listitem>
80 <para>
81 Required patch:
82 <ulink url="&patch-root;/polkit-&polkit-version;-js91-1.patch"/>
83 </para>
84 </listitem>
85 </itemizedlist>
86-->
87
88 <bridgehead renderas="sect3">Polkit Dependencies</bridgehead>
89
90 <bridgehead renderas="sect4">Required</bridgehead>
91 <para role="required">
92 <xref linkend="glib2"/>
93 </para>
94
95 <bridgehead renderas="sect4">Recommended</bridgehead>
96 <para role="recommended">
97 <!-- For jhalfs just make it required to avoid over-complexity. -->
98 <xref role="required" linkend="duktape"/>,
99 <xref linkend="gobject-introspection"/>,
100 <xref linkend="libxslt"/>,<phrase revision="systemd"> and</phrase>
101 <xref linkend="linux-pam"/><phrase revision="sysv">, and
102 <xref linkend="elogind"/>
103 </phrase>
104 </para>
105
106 <note>
107 <para>
108 Since <phrase revision="sysv"><command>elogind</command></phrase>
109 <phrase revision="systemd"><command>systemd-logind</command></phrase>
110 uses PAM to register user sessions, it is a good idea to build
111 <application>Polkit</application> with PAM support so
112 <phrase revision="sysv"><command>elogind</command></phrase>
113 <phrase revision="systemd"><command>systemd-logind</command></phrase>
114 can track <application>Polkit</application> sessions.
115 </para>
116 </note>
117
118
119 <!-- Due to the fact that meson will not autodetect g-i and
120 has it set to required unless you pass an option, and the likelihood
121 of users ignoring a command explanation and then sending in mails
122 regarding KDE or GNOME not working after installing polkit, let's move
123 it to recommended. See #15640 for logic
124 <bridgehead renderas="sect4">Optional (Required if building GNOME)</bridgehead>
125 <para role="optional">
126 <xref linkend="gobject-introspection"/>
127 </para>
128 -->
129
130 <bridgehead renderas="sect4">Optional</bridgehead>
131 <para role="optional">
132 <xref linkend="gtk-doc"/>,
133 <xref linkend="js102"/> (can be used in place of duktape), and
134 <xref linkend="python-dbusmock"/> (for tests)
135 </para>
136
137 <bridgehead renderas="sect4" revision="systemd">Required Runtime Dependencies</bridgehead>
138 <para role="required" revision="systemd">
139 <xref role="runtime" linkend="systemd"/>
140 </para>
141
142 <bridgehead renderas="sect4" id="polkit-agent" xreflabel="Polkit Authentication Agent">
143 Optional Runtime Dependencies
144 </bridgehead>
145 <para role="optional">
146 One polkit authentication agent for using polkit in the graphical
147 environment:
148 <application>polkit-kde-agent</application> in
149 <xref role="runtime" linkend="plasma5-build"/> for KDE,
150 the agent built in
151 <xref role="runtime" linkend="gnome-shell"/> for GNOME3,
152 <xref role="runtime" linkend="polkit-gnome"/> for XFCE, and
153 <application>lxpolkit</application> in
154 <xref role="runtime" linkend="lxsession"/> for LXDE
155 </para>
156
157 <note>
158 <para>
159 If <xref linkend="libxslt"/> is installed,
160 then <xref linkend="DocBook"/> and <xref linkend="docbook-xsl"/> are
161 required. If you have installed <xref linkend="libxslt"/>, but you do
162 not want to install any of the DocBook packages mentioned, you will
163 need to use <option>-Dman=false</option> in the instructions
164 below.
165 </para>
166 </note>
167
168 </sect2>
169
170 <sect2 role="installation">
171 <title>Installation of Polkit</title>
172
173 <para>
174 There should be a dedicated user and group to take control
175 of the <command>polkitd</command> daemon after it is
176 started. Issue the following commands as the
177 <systemitem class="username">root</systemitem> user:
178 </para>
179
180<screen role="root"><userinput>groupadd -fg 27 polkitd &amp;&amp;
181useradd -c "PolicyKit Daemon Owner" -d /etc/polkit-1 -u 27 \
182 -g polkitd -s /bin/false polkitd</userinput></screen>
183
184 <para>
185 If using <xref linkend="js102"/>, make the following change (see Command
186 Explanations below for more information):
187 </para>
188
189<screen><userinput remap="nodump">sed -e 's/JS_Init/JS::DisableJitBackend(); &amp;/' \
190 -i src/polkitbackend/polkitbackendjsauthority.cpp</userinput></screen>
191
192<!--
193 <para>
194 Apply a patch to fix two security issues:
195 </para>
196
197<screen><userinput remap="pre">patch -Np1 -i ../polkit-&polkit-version;-security_fixes-1.patch</userinput></screen>
198
199 <para>
200 Port this package to use JS-91:
201 </para>
202
203<screen><userinput remap="pre">patch -Np1 -i ../polkit-&polkit-version;-js91-1.patch</userinput></screen>
204-->
205
206 <para>
207 Install <application>Polkit</application> by running the following
208 commands:
209 </para>
210
211<screen revision="systemd"><userinput>mkdir build &amp;&amp;
212cd build &amp;&amp;
213
214meson setup .. \
215 --prefix=/usr \
216 --buildtype=release \
217 -Dman=true \
218 -Dsession_tracking=libsystemd-login \
219 -Dtests=true &amp;&amp;
220ninja</userinput></screen>
221
222<screen revision="sysv"><userinput>mkdir build &amp;&amp;
223cd build &amp;&amp;
224
225meson setup .. \
226 --prefix=/usr \
227 --buildtype=release \
228 -Dman=true \
229 -Dsession_tracking=libelogind \
230 -Dtests=true &amp;&amp;
231ninja</userinput></screen>
232
233 <para>
234 To test the results, first ensure that the system
235 <application>D-Bus</application> daemon is running,
236 and both <xref linkend='dbus-python'/> and
237 <xref linkend='python-dbusmock'/> are installed.
238 Then run <command>ninja test</command>.
239 </para>
240
241 <para>
242 Now, as the <systemitem class="username">root</systemitem> user:
243 </para>
244
245<screen role="root"><userinput>ninja install</userinput></screen>
246
247 </sect2>
248
249 <sect2 role="commands">
250 <title>Command Explanations</title>
251
252 <para>
253 <command>sed -e 's/JS_Init/JS::DisableJitBackend(); &amp;/' ...
254 </command>: The JIT compiling of JS102 needs W+X mapping which
255 is dangerous and is not permitted by the
256 <application>systemd</application> unit file shipped within the polkit
257 package. This command is not strictly needed on systems based on
258 sysvinit but it still improves security. It has no effect if building
259 polkit with the recommended <xref linkend='duktape'/> Javascript
260 engine.
261 </para>
262
263 <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
264 href="../../xincludes/meson-buildtype-release.xml"/>
265
266 <para>
267 <parameter>-Dtests=true</parameter>: This switch allows to run the
268 test suite of this package. As <application>Polkit</application> is
269 used for authorizations, its integrity can affect system security.
270 So it's recommended to run the test suite building this package.
271 </para>
272
273 <para>
274 <option>-Djs_engine=mozjs</option>: This switch allows using the
275 <xref linkend="js102"/> JavaScript engine instead of the
276 <xref linkend='duktape'/> JavaScript engine.
277 </para>
278
279 <!--
280 <para revision="sysv">
281 <parameter>- -disable-libsystemd-login</parameter>: This switch forces
282 polkit to build with elogind support (if available) rather than
283 systemd-logind.
284 </para>
285
286
287 <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
288 href="../../xincludes/static-libraries.xml"/>
289 -->
290
291 <para>
292 <option>-Dos_type=lfs</option>: Use this switch if you did not create
293 the <filename>/etc/lfs-release</filename> file or distribution auto
294 detection will fail and you will be unable to use
295 <application>Polkit</application>.
296 </para>
297
298 <para>
299 <option>-Dauthfw=shadow</option>: This switch enables the
300 package to use the <application>Shadow</application> rather than the
301 <application>Linux PAM</application> Authentication framework. Use it
302 if you have not installed <application>Linux PAM</application>.
303 </para>
304
305 <!--
306 <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
307 href="../../xincludes/gtk-doc-rebuild.xml"/>
308 -->
309
310 <para>
311 <option>-Dintrospection=false</option>: Use this option if you are certain
312 that you do not need gobject-introspection files for polkit, or do not have
313 gobject-introspection installed.
314 </para>
315
316 <para>
317 <option>-Dman=false</option>: Use this option to disable generating and
318 installing manual pages. This is useful if libxslt is not installed.
319 </para>
320
321 <para>
322 <option>-Dexamples=true</option>: Use this option to build the example
323 programs.
324 </para>
325
326 <para>
327 <option>-Dgtk_doc=true</option>: Use this option to enable building and
328 installing the API documentation.
329 </para>
330
331 </sect2>
332
333 <sect2 role="content">
334 <title>Contents</title>
335
336 <segmentedlist>
337 <segtitle>Installed Programs</segtitle>
338 <segtitle>Installed Libraries</segtitle>
339 <segtitle>Installed Directories</segtitle>
340
341 <seglistitem>
342 <seg>
343 pkaction, pkcheck, <!--pk-example-frobnicate,--> pkexec,
344 pkttyagent, and polkitd
345 </seg>
346 <seg>
347 libpolkit-agent-1.so and
348 libpolkit-gobject-1.so
349 </seg>
350 <seg>
351 /etc/polkit-1,
352 /usr/include/polkit-1,
353 /usr/lib/polkit-1,
354 /usr/share/gtk-doc/html/polkit-1, and
355 /usr/share/polkit-1
356 </seg>
357 </seglistitem>
358 </segmentedlist>
359
360 <variablelist>
361 <bridgehead renderas="sect3">Short Descriptions</bridgehead>
362 <?dbfo list-presentation="list"?>
363 <?dbhtml list-presentation="table"?>
364
365 <varlistentry id="pkaction">
366 <term><command>pkaction</command></term>
367 <listitem>
368 <para>
369 is used to obtain information about registered PolicyKit actions
370 </para>
371 <indexterm zone="polkit pkaction">
372 <primary sortas="b-pkaction">pkaction</primary>
373 </indexterm>
374 </listitem>
375 </varlistentry>
376
377 <varlistentry id="pkcheck">
378 <term><command>pkcheck</command></term>
379 <listitem>
380 <para>
381 is used to check whether a process is authorized for action
382 </para>
383 <indexterm zone="polkit pkcheck">
384 <primary sortas="b-pkcheck">pkcheck</primary>
385 </indexterm>
386 </listitem>
387 </varlistentry>
388
389<!--
390 <varlistentry id="pk-example-frobnicate">
391 <term><command>pk-example-frobnicate</command></term>
392 <listitem>
393 <para>
394 is an example program to test the <command>pkexec</command>
395 command
396 </para>
397 <indexterm zone="polkit pk-example-frobnicate">
398 <primary sortas="b-pk-example-frobnicate">pk-example-frobnicate</primary>
399 </indexterm>
400 </listitem>
401 </varlistentry>
402-->
403
404 <varlistentry id="pkexec">
405 <term><command>pkexec</command></term>
406 <listitem>
407 <para>
408 allows an authorized user to execute a command as another user
409 </para>
410 <indexterm zone="polkit pkexec">
411 <primary sortas="b-pkexec">pkexec</primary>
412 </indexterm>
413 </listitem>
414 </varlistentry>
415
416 <varlistentry id="pkttyagent">
417 <term><command>pkttyagent</command></term>
418 <listitem>
419 <para>
420 is used to start a textual authentication agent for the subject
421 </para>
422 <indexterm zone="polkit pkttyagent">
423 <primary sortas="b-pkttyagent">pkttyagent</primary>
424 </indexterm>
425 </listitem>
426 </varlistentry>
427
428 <varlistentry id="polkitd">
429 <term><command>polkitd</command></term>
430 <listitem>
431 <para>
432 provides the org.freedesktop.PolicyKit1 <application>D-Bus</application>
433 service on the system message bus
434 </para>
435 <indexterm zone="polkit polkitd">
436 <primary sortas="b-polkitd">polkitd</primary>
437 </indexterm>
438 </listitem>
439 </varlistentry>
440
441 <varlistentry id="libpolkit-agent-1">
442 <term><filename class="libraryfile">libpolkit-agent-1.so</filename></term>
443 <listitem>
444 <para>
445 contains the <application>Polkit</application> authentication
446 agent API functions
447 </para>
448 <indexterm zone="polkit libpolkit-agent-1">
449 <primary sortas="c-libpolkit-agent-1">libpolkit-agent-1.so</primary>
450 </indexterm>
451 </listitem>
452 </varlistentry>
453
454 <varlistentry id="libpolkit-gobject-1">
455 <term><filename class="libraryfile">libpolkit-gobject-1.so</filename></term>
456 <listitem>
457 <para>
458 contains the <application>Polkit</application> authorization API functions
459 </para>
460 <indexterm zone="polkit libpolkit-gobject-1">
461 <primary sortas="c-libpolkit-gobject-1">libpolkit-gobject-1.so</primary>
462 </indexterm>
463 </listitem>
464 </varlistentry>
465
466 </variablelist>
467
468 </sect2>
469
470</sect1>
Note: See TracBrowser for help on using the repository browser.