source: postlfs/security/polkit.xml@ 7cb4635

trunk
Last change on this file since 7cb4635 was 7cb4635, checked in by Pierre Labastie <pierre.labastie@…>, 2 months ago

Recommend a build order for elogind<->polkit circular dep

  • Property mode set to 100644
File size: 13.9 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://www.freedesktop.org/software/polkit/releases/polkit-&polkit-version;.tar.gz">
8 <!ENTITY polkit-download-ftp " ">
9 <!ENTITY polkit-md5sum "ae3f2a742740069922589ad20ffd54d2">
10 <!ENTITY polkit-size "1.5 MB">
11 <!ENTITY polkit-buildsize "17 MB (add 2 MB for tests)">
12 <!ENTITY polkit-time "0.1 SBU (Using parallelism=4; add 0.3 SBU for tests)">
13]>
14
15<sect1 id="polkit" xreflabel="Polkit-&polkit-version;">
16 <?dbhtml filename="polkit.html"?>
17
18 <sect1info>
19 <date>$Date$</date>
20 </sect1info>
21
22 <title>Polkit-&polkit-version;</title>
23
24 <indexterm zone="polkit">
25 <primary sortas="a-Polkit">Polkit</primary>
26 </indexterm>
27
28 <sect2 role="package">
29 <title>Introduction to Polkit</title>
30
31 <para>
32 <application>Polkit</application> is a toolkit for defining and handling
33 authorizations. It is used for allowing unprivileged processes to
34 communicate with privileged processes.
35 </para>
36
37 &lfs101_checked;
38
39 <bridgehead renderas="sect3">Package Information</bridgehead>
40 <itemizedlist spacing="compact">
41 <listitem>
42 <para>
43 Download (HTTP): <ulink url="&polkit-download-http;"/>
44 </para>
45 </listitem>
46 <listitem>
47 <para>
48 Download (FTP): <ulink url="&polkit-download-ftp;"/>
49 </para>
50 </listitem>
51 <listitem>
52 <para>
53 Download MD5 sum: &polkit-md5sum;
54 </para>
55 </listitem>
56 <listitem>
57 <para>
58 Download size: &polkit-size;
59 </para>
60 </listitem>
61 <listitem>
62 <para>
63 Estimated disk space required: &polkit-buildsize;
64 </para>
65 </listitem>
66 <listitem>
67 <para>
68 Estimated build time: &polkit-time;
69 </para>
70 </listitem>
71 </itemizedlist>
72
73 <bridgehead renderas="sect3"
74 revision="sysv">Additional Downloads</bridgehead>
75 <itemizedlist spacing="compact" revision="sysv">
76 <listitem>
77 <para>
78 Recommended patch:
79 <ulink url="&patch-root;/polkit-&polkit-version;-fix_elogind_detection-1.patch"/>
80 </para>
81 </listitem>
82 </itemizedlist>
83
84 <bridgehead renderas="sect3">Polkit Dependencies</bridgehead>
85
86 <bridgehead renderas="sect4">Required</bridgehead>
87 <para role="required">
88 <xref linkend="glib2"/> and
89 <xref linkend="js78"/>
90 </para>
91
92 <bridgehead renderas="sect4">Recommended</bridgehead>
93 <para role="recommended">
94 <xref linkend="linux-pam"/>
95 <phrase revision="sysv">
96 and <xref role="first" linkend="elogind"/> (circular, build
97 elogind first, then polkit, then elogind again).
98 </phrase>
99 </para>
100
101 <note>
102 <para>
103 Since <phrase revision="sysv"><command>elogind</command></phrase>
104 <phrase revision="systemd"><command>systemd-logind</command></phrase>
105 uses PAM to register user sessions, it is a good idea to build
106 <application>Polkit</application> with PAM support so
107 <phrase revision="sysv"><command>elogind</command></phrase>
108 <phrase revision="systemd"><command>systemd-logind</command></phrase>
109 can track <application>Polkit</application> sessions.
110 </para>
111 </note>
112
113
114 <bridgehead renderas="sect4">Optional (Required if building GNOME)</bridgehead>
115 <para role="optional">
116 <xref linkend="gobject-introspection"/>
117 </para>
118
119 <bridgehead renderas="sect4">Optional</bridgehead>
120 <para role="optional">
121 <xref linkend="dbus-python"/> and
122 <xref linkend="python-dbusmock"/> (for tests),
123 <xref linkend="DocBook"/>,
124 <xref linkend="docbook-xsl"/>,
125 <xref linkend="gtk-doc"/>, and
126 <xref linkend="libxslt"/>
127 </para>
128
129 <bridgehead renderas="sect4" revision="systemd">Required Runtime Dependencies</bridgehead>
130 <para role="required" revision="systemd">
131 <xref role="runtime" linkend="systemd"/>
132 </para>
133
134 <bridgehead renderas="sect4" id="polkit-agent" xreflabel="Polkit Authentication Agent">
135 Optional Runtime Dependencies
136 </bridgehead>
137 <para role="optional">
138 One polkit authentication agent for using polkit in the graphical
139 environment:
140 <application>polkit-kde-agent</application> in
141 <xref role="runtime" linkend="plasma5-build"/> for KDE,
142 the agent built in
143 <xref role="runtime" linkend="gnome-shell"/> for GNOME3,
144 <xref role="runtime" linkend="polkit-gnome"/> for XFCE, and
145 <application>lxpolkit</application> in
146 <xref role="runtime" linkend="lxsession"/> for LXDE.
147 </para>
148
149 <note>
150 <para>
151 If <xref linkend="libxslt"/> is installed,
152 then <xref linkend="DocBook"/> and <xref linkend="docbook-xsl"/> are
153 required. If you have installed <xref linkend="libxslt"/>, but you do
154 not want to install any of the DocBook packages mentioned, you will
155 need to use <option>--disable-man-pages</option> in the instructions
156 below.
157 </para>
158 </note>
159
160 <para condition="html" role="usernotes">User Notes:
161 <ulink url="&blfs-wiki;/polkit"/>
162 </para>
163 </sect2>
164
165 <sect2 role="installation">
166 <title>Installation of Polkit</title>
167
168 <para>
169 There should be a dedicated user and group to take control
170 of the <command>polkitd</command> daemon after it is
171 started. Issue the following commands as the
172 <systemitem class="username">root</systemitem> user:
173 </para>
174
175<screen role="root"><userinput>groupadd -fg 27 polkitd &amp;&amp;
176useradd -c "PolicyKit Daemon Owner" -d /etc/polkit-1 -u 27 \
177 -g polkitd -s /bin/false polkitd</userinput></screen>
178
179 <note revision="systemd">
180 <para>
181 When building <application>Polkit</application> with
182 <application>systemd</application> logind support, the
183 <command>configure</command> script explicitly checks if
184 system is booted using <application>systemd</application>.
185 This can cause problems if building the package in chroot,
186 where the <command>configure</command> would fail to
187 detect <application>systemd</application>. To workaround
188 the problem, simply run the following command:
189 </para>
190
191<screen><userinput>sed -i "s:/sys/fs/cgroup/systemd/:/sys:g" configure</userinput></screen>
192 </note>
193
194 <para revision="sysv">
195 Fix an issue introduced in recent <application>Polkit</application>
196 releases with elogind:
197 </para>
198
199<screen revision="sysv"><userinput>patch -Np1 -i ../polkit-&polkit-version;-fix_elogind_detection-1.patch &amp;&amp;
200autoreconf -fv</userinput></screen>
201
202 <para>
203 Install <application>Polkit</application> by running the following
204 commands:
205 </para>
206
207<screen revision="systemd"><userinput>./configure --prefix=/usr \
208 --sysconfdir=/etc \
209 --localstatedir=/var \
210 --disable-static \
211 --with-os-type=LFS &amp;&amp;
212make</userinput></screen>
213
214<screen revision="sysv"><userinput>./configure --prefix=/usr \
215 --sysconfdir=/etc \
216 --localstatedir=/var \
217 --disable-static \
218 --with-os-type=LFS \
219 --disable-libsystemd-login &amp;&amp;
220make</userinput></screen>
221
222 <para>
223 To test the results, first ensure that the system
224 <application>D-Bus</application> daemon is running.
225 Then run <command>make check</command>.
226 </para>
227
228 <para>
229 Now, as the <systemitem class="username">root</systemitem> user:
230 </para>
231
232<screen role="root"><userinput>make install</userinput></screen>
233
234 </sect2>
235
236 <sect2 role="commands">
237 <title>Command Explanations</title>
238
239 <para revision="sysv">
240 <parameter>--disable-libsystemd-login</parameter>: This switch forces
241 polkit to build with elogind support (if available) rather than
242 systemd-logind.
243 </para>
244
245 <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
246 href="../../xincludes/static-libraries.xml"/>
247
248 <para>
249 <option>--with-authfw=shadow</option>: This switch enables the
250 package to use the <application>Shadow</application> rather than the
251 <application>Linux PAM</application> Authentication framework. Use it
252 if you have not installed <application>Linux PAM</application>.
253 </para>
254
255 <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
256 href="../../xincludes/gtk-doc-rebuild.xml"/>
257
258 </sect2>
259
260 <sect2 role="configuration">
261 <title>Configuring Polkit</title>
262
263 <sect3>
264 <title>PAM Configuration</title>
265
266 <note>
267 <para>
268 If you did not build <application>Polkit</application> with
269 <application>Linux PAM</application> support, you can skip this
270 section.
271 </para>
272 </note>
273
274 <para>
275 If you have built <application>Polkit</application> with
276 <application>Linux PAM</application> support, you need to modify
277 the default PAM configuration file which was installed by default to get
278 <application>Polkit</application> to work correctly with BLFS. Issue the
279 following commands as the <systemitem class="username">root</systemitem>
280 user to create the configuration file for <application>Linux PAM</application>:
281 </para>
282
283<screen role="root"><userinput>cat &gt; /etc/pam.d/polkit-1 &lt;&lt; "EOF"
284<literal># Begin /etc/pam.d/polkit-1
285
286auth include system-auth
287account include system-account
288password include system-password
289session include system-session
290
291# End /etc/pam.d/polkit-1</literal>
292EOF</userinput></screen>
293
294 </sect3>
295
296 </sect2>
297
298 <sect2 role="content">
299 <title>Contents</title>
300
301 <segmentedlist>
302 <segtitle>Installed Programs</segtitle>
303 <segtitle>Installed Libraries</segtitle>
304 <segtitle>Installed Directories</segtitle>
305
306 <seglistitem>
307 <seg>
308 pkaction, pkcheck, pk-example-frobnicate, pkexec,
309 pkttyagent and polkitd
310 </seg>
311 <seg>
312 libpolkit-agent-1.so and
313 libpolkit-gobject-1.so
314 </seg>
315 <seg>
316 /etc/polkit-1,
317 /usr/include/polkit-1,
318 /usr/lib/polkit-1,
319 /usr/share/gtk-doc/html/polkit-1 and
320 /usr/share/polkit-1
321 </seg>
322 </seglistitem>
323 </segmentedlist>
324
325 <variablelist>
326 <bridgehead renderas="sect3">Short Descriptions</bridgehead>
327 <?dbfo list-presentation="list"?>
328 <?dbhtml list-presentation="table"?>
329
330 <varlistentry id="pkaction">
331 <term><command>pkaction</command></term>
332 <listitem>
333 <para>
334 is used to obtain information about registered PolicyKit actions
335 </para>
336 <indexterm zone="polkit pkaction">
337 <primary sortas="b-pkaction">pkaction</primary>
338 </indexterm>
339 </listitem>
340 </varlistentry>
341
342 <varlistentry id="pkcheck">
343 <term><command>pkcheck</command></term>
344 <listitem>
345 <para>
346 is used to check whether a process is authorized for action
347 </para>
348 <indexterm zone="polkit pkcheck">
349 <primary sortas="b-pkcheck">pkcheck</primary>
350 </indexterm>
351 </listitem>
352 </varlistentry>
353
354 <varlistentry id="pk-example-frobnicate">
355 <term><command>pk-example-frobnicate</command></term>
356 <listitem>
357 <para>
358 is an example program to test the <command>pkexec</command>
359 command
360 </para>
361 <indexterm zone="polkit pk-example-frobnicate">
362 <primary sortas="b-pk-example-frobnicate">pk-example-frobnicate</primary>
363 </indexterm>
364 </listitem>
365 </varlistentry>
366
367 <varlistentry id="pkexec">
368 <term><command>pkexec</command></term>
369 <listitem>
370 <para>
371 allows an authorized user to execute a command as another user
372 </para>
373 <indexterm zone="polkit pkexec">
374 <primary sortas="b-pkexec">pkexec</primary>
375 </indexterm>
376 </listitem>
377 </varlistentry>
378
379 <varlistentry id="pkttyagent">
380 <term><command>pkttyagent</command></term>
381 <listitem>
382 <para>
383 is used to start a textual authentication agent for the subject
384 </para>
385 <indexterm zone="polkit pkttyagent">
386 <primary sortas="b-pkttyagent">pkttyagent</primary>
387 </indexterm>
388 </listitem>
389 </varlistentry>
390
391 <varlistentry id="polkitd">
392 <term><command>polkitd</command></term>
393 <listitem>
394 <para>
395 provides the org.freedesktop.PolicyKit1 <application>D-Bus</application>
396 service on the system message bus
397 </para>
398 <indexterm zone="polkit polkitd">
399 <primary sortas="b-polkitd">polkitd</primary>
400 </indexterm>
401 </listitem>
402 </varlistentry>
403
404 <varlistentry id="libpolkit-agent-1">
405 <term><filename class="libraryfile">libpolkit-agent-1.so</filename></term>
406 <listitem>
407 <para>
408 contains the <application>Polkit</application> authentication
409 agent API functions
410 </para>
411 <indexterm zone="polkit libpolkit-agent-1">
412 <primary sortas="c-libpolkit-agent-1">libpolkit-agent-1.so</primary>
413 </indexterm>
414 </listitem>
415 </varlistentry>
416
417 <varlistentry id="libpolkit-gobject-1">
418 <term><filename class="libraryfile">libpolkit-gobject-1.so</filename></term>
419 <listitem>
420 <para>
421 contains the <application>Polkit</application> authorization API functions
422 </para>
423 <indexterm zone="polkit libpolkit-gobject-1">
424 <primary sortas="c-libpolkit-gobject-1">libpolkit-gobject-1.so</primary>
425 </indexterm>
426 </listitem>
427 </varlistentry>
428
429 </variablelist>
430
431 </sect2>
432
433</sect1>
Note: See TracBrowser for help on using the repository browser.