source: postlfs/security/polkit.xml@ faa948c

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
  <!ENTITY % general-entities SYSTEM "../../general.ent">
  %general-entities;

  <!ENTITY polkit-download-http "https://gitlab.freedesktop.org/polkit/polkit/-/archive/&polkit-version;/polkit-&polkit-version;.tar.gz">
  <!ENTITY polkit-download-ftp  " ">
  <!ENTITY polkit-md5sum        "36540b837c588e1e77145523bb39f511">
  <!ENTITY polkit-size          "736 KB">
  <!ENTITY polkit-buildsize     "6.8 MB (with tests)">
  <!ENTITY polkit-time          "0.3 SBU (with tests, using parallelism=4)">
]>

<sect1 id="polkit" xreflabel="Polkit-&polkit-version;">
  <?dbhtml filename="polkit.html"?>


  <title>Polkit-&polkit-version;</title>

  <indexterm zone="polkit">
    <primary sortas="a-Polkit">Polkit</primary>
  </indexterm>

  <sect2 role="package">
    <title>Introduction to Polkit</title>

    <para>
      <application>Polkit</application> is a toolkit for defining and handling
      authorizations. It is used for allowing unprivileged processes to
      communicate with privileged processes.
    </para>

    &lfs120_checked;

    <bridgehead renderas="sect3">Package Information</bridgehead>
    <itemizedlist spacing="compact">
      <listitem>
        <para>
          Download (HTTP): <ulink url="&polkit-download-http;"/>
        </para>
      </listitem>
      <listitem>
        <para>
          Download (FTP): <ulink url="&polkit-download-ftp;"/>
        </para>
      </listitem>
      <listitem>
        <para>
          Download MD5 sum: &polkit-md5sum;
        </para>
      </listitem>
      <listitem>
        <para>
          Download size: &polkit-size;
        </para>
      </listitem>
      <listitem>
        <para>
          Estimated disk space required: &polkit-buildsize;
        </para>
      </listitem>
      <listitem>
        <para>
          Estimated build time: &polkit-time;
        </para>
      </listitem>
    </itemizedlist>

<!--
    <bridgehead renderas="sect3">Additional Downloads</bridgehead>
    <itemizedlist spacing="compact">
      <listitem>
        <para>
          Required patch:
          <ulink url="&patch-root;/polkit-&polkit-version;-security_fixes-1.patch"/>
        </para>
      </listitem>
      <listitem>
        <para>
          Required patch:
          <ulink url="&patch-root;/polkit-&polkit-version;-js91-1.patch"/>
        </para>
      </listitem>
    </itemizedlist>
-->

    <bridgehead renderas="sect3">Polkit Dependencies</bridgehead>

    <bridgehead renderas="sect4">Required</bridgehead>
    <para role="required">
      <xref linkend="glib2"/>
    </para>

    <bridgehead renderas="sect4">Recommended</bridgehead>
    <para role="recommended">
      <!-- For jhalfs just make it required to avoid over-complexity. -->
      <xref role="required" linkend="duktape"/>,
      <xref linkend="gobject-introspection"/>,
      <xref linkend="libxslt"/>,<phrase revision="systemd"> and</phrase>
      <xref linkend="linux-pam"/><phrase revision="sysv">, and
        <xref linkend="elogind"/>
      </phrase>
    </para>

    <note>
      <para>
        Since <phrase revision="sysv"><command>elogind</command></phrase>
        <phrase revision="systemd"><command>systemd-logind</command></phrase>
        uses PAM to register user sessions, it is a good idea to build
        <application>Polkit</application> with PAM support so
        <phrase revision="sysv"><command>elogind</command></phrase>
        <phrase revision="systemd"><command>systemd-logind</command></phrase>
        can track <application>Polkit</application> sessions.
      </para>
    </note>


    <!-- Due to the fact that meson will not autodetect g-i and
         has it set to required unless you pass an option, and the likelihood
         of users ignoring a command explanation and then sending in mails
         regarding KDE or GNOME not working after installing polkit, let's move
         it to recommended. See #15640 for logic
    <bridgehead renderas="sect4">Optional (Required if building GNOME)</bridgehead>
    <para role="optional">
      <xref linkend="gobject-introspection"/>
    </para>
    -->

    <bridgehead renderas="sect4">Optional</bridgehead>
    <para role="optional">
      <xref linkend="gtk-doc"/>,
      <xref linkend="js102"/> (can be used in place of duktape), and
      <xref linkend="python-dbusmock"/> (for tests)
    </para>

    <bridgehead renderas="sect4" revision="systemd">Required Runtime Dependencies</bridgehead>
    <para role="required" revision="systemd">
      <xref role="runtime" linkend="systemd"/>
    </para>

    <bridgehead renderas="sect4" id="polkit-agent" xreflabel="Polkit Authentication Agent">
      Optional Runtime Dependencies
    </bridgehead>
    <para role="optional">
      One polkit authentication agent for using polkit in the graphical
      environment:
      <application>polkit-kde-agent</application> in
      <xref role="runtime" linkend="plasma5-build"/> for KDE,
      the agent built in
      <xref role="runtime" linkend="gnome-shell"/> for GNOME3,
      <xref role="runtime" linkend="polkit-gnome"/> for XFCE, and
      <application>lxpolkit</application> in
      <xref role="runtime" linkend="lxsession"/> for LXDE
    </para>

    <note>
      <para>
        If <xref linkend="libxslt"/> is installed,
        then <xref linkend="DocBook"/> and <xref linkend="docbook-xsl"/> are
        required. If you have installed <xref linkend="libxslt"/>, but you do
        not want to install any of the DocBook packages mentioned, you will
        need to use <option>-Dman=false</option> in the instructions
        below.
      </para>
    </note>

  </sect2>

  <sect2 role="installation">
    <title>Installation of Polkit</title>

    <para>
      There should be a dedicated user and group to take control
      of the <command>polkitd</command> daemon after it is
      started. Issue the following commands as the
      <systemitem class="username">root</systemitem> user:
    </para>

<screen role="root"><userinput>groupadd -fg 27 polkitd &amp;&amp;
useradd -c "PolicyKit Daemon Owner" -d /etc/polkit-1 -u 27 \
        -g polkitd -s /bin/false polkitd</userinput></screen>

    <para>
      If using <xref linkend="js102"/>, make the following change (see Command 
      Explanations below for more information):
    </para>

<screen><userinput remap="nodump">sed -e 's/JS_Init/JS::DisableJitBackend(); &amp;/' \
    -i src/polkitbackend/polkitbackendjsauthority.cpp</userinput></screen>

<!--
    <para>
      Apply a patch to fix two security issues:
    </para>

<screen><userinput remap="pre">patch -Np1 -i ../polkit-&polkit-version;-security_fixes-1.patch</userinput></screen>

    <para>
      Port this package to use JS-91:
    </para>

<screen><userinput remap="pre">patch -Np1 -i ../polkit-&polkit-version;-js91-1.patch</userinput></screen>
-->

    <para>
      Install <application>Polkit</application> by running the following
      commands:
    </para>

<screen revision="systemd"><userinput>mkdir build &amp;&amp;
cd    build &amp;&amp;

meson setup ..                            \
      --prefix=/usr                       \
      --buildtype=release                 \
      -Dman=true                          \
      -Dsession_tracking=libsystemd-login \
      -Dtests=true                        &amp;&amp;
ninja</userinput></screen>

<screen revision="sysv"><userinput>mkdir build &amp;&amp;
cd    build &amp;&amp;

meson setup ..                      \
      --prefix=/usr                 \
      --buildtype=release           \
      -Dman=true                    \
      -Dsession_tracking=libelogind \
      -Dtests=true                  &amp;&amp;
ninja</userinput></screen>

    <para>
      To test the results, first ensure that the system
      <application>D-Bus</application> daemon is running,
      and both <xref linkend='dbus-python'/> and
      <xref linkend='python-dbusmock'/> are installed.
      Then run <command>ninja test</command>.
    </para>

    <para>
      Now, as the <systemitem class="username">root</systemitem> user:
    </para>

<screen role="root"><userinput>ninja install</userinput></screen>

  </sect2>

  <sect2 role="commands">
    <title>Command Explanations</title>

    <para>
      <command>sed -e 's/JS_Init/JS::DisableJitBackend(); &amp;/' ...
      </command>: The JIT compiling of JS102 needs W+X mapping which
      is dangerous and is not permitted by the
      <application>systemd</application> unit file shipped within the polkit
      package.  This command is not strictly needed on systems based on
      sysvinit but it still improves security.  It has no effect if building
      polkit with the recommended <xref linkend='duktape'/> Javascript
      engine.
    </para>

    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
      href="../../xincludes/meson-buildtype-release.xml"/>

    <para>
      <parameter>-Dtests=true</parameter>: This switch allows to run the
      test suite of this package.  As <application>Polkit</application> is
      used for authorizations, its integrity can affect system security.
      So it's recommended to run the test suite building this package.
    </para>

    <para>
      <option>-Djs_engine=mozjs</option>: This switch allows using the
      <xref linkend="js102"/> JavaScript engine instead of the
      <xref linkend='duktape'/> JavaScript engine.
    </para>

    <!--
    <para revision="sysv">
      <parameter>- -disable-libsystemd-login</parameter>: This switch forces
      polkit to build with elogind support (if available) rather than
      systemd-logind.
    </para>


    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
      href="../../xincludes/static-libraries.xml"/>
    -->

    <para>
      <option>-Dos_type=lfs</option>: Use this switch if you did not create
      the <filename>/etc/lfs-release</filename> file or distribution auto
      detection will fail and you will be unable to use
      <application>Polkit</application>.
    </para>

    <para>
      <option>-Dauthfw=shadow</option>: This switch enables the
      package to use the <application>Shadow</application> rather than the
      <application>Linux PAM</application> Authentication framework. Use it
      if you have not installed <application>Linux PAM</application>.
    </para>

    <!--
    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
    href="../../xincludes/gtk-doc-rebuild.xml"/>
    -->

    <para>
      <option>-Dintrospection=false</option>: Use this option if you are certain
      that you do not need gobject-introspection files for polkit, or do not have
      gobject-introspection installed.
    </para>

    <para>
      <option>-Dman=false</option>: Use this option to disable generating and
      installing manual pages. This is useful if libxslt is not installed.
    </para>

    <para>
      <option>-Dexamples=true</option>: Use this option to build the example
      programs.
    </para>

    <para>
      <option>-Dgtk_doc=true</option>: Use this option to enable building and
      installing the API documentation.
    </para>

  </sect2>

  <sect2 role="content">
    <title>Contents</title>

    <segmentedlist>
      <segtitle>Installed Programs</segtitle>
      <segtitle>Installed Libraries</segtitle>
      <segtitle>Installed Directories</segtitle>

      <seglistitem>
        <seg>
          pkaction, pkcheck, <!--pk-example-frobnicate,--> pkexec,
          pkttyagent, and polkitd
        </seg>
        <seg>
          libpolkit-agent-1.so and
          libpolkit-gobject-1.so
        </seg>
        <seg>
          /etc/polkit-1,
          /usr/include/polkit-1,
          /usr/lib/polkit-1,
          /usr/share/gtk-doc/html/polkit-1, and
          /usr/share/polkit-1
        </seg>
      </seglistitem>
    </segmentedlist>

    <variablelist>
      <bridgehead renderas="sect3">Short Descriptions</bridgehead>
      <?dbfo list-presentation="list"?>
      <?dbhtml list-presentation="table"?>

      <varlistentry id="pkaction">
        <term><command>pkaction</command></term>
        <listitem>
          <para>
            is used to obtain information about registered PolicyKit actions
          </para>
          <indexterm zone="polkit pkaction">
            <primary sortas="b-pkaction">pkaction</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="pkcheck">
        <term><command>pkcheck</command></term>
        <listitem>
          <para>
            is used to check whether a process is authorized for action
          </para>
          <indexterm zone="polkit pkcheck">
            <primary sortas="b-pkcheck">pkcheck</primary>
          </indexterm>
        </listitem>
      </varlistentry>

<!--
      <varlistentry id="pk-example-frobnicate">
        <term><command>pk-example-frobnicate</command></term>
        <listitem>
          <para>
            is an example program to test the <command>pkexec</command>
            command
          </para>
          <indexterm zone="polkit pk-example-frobnicate">
            <primary sortas="b-pk-example-frobnicate">pk-example-frobnicate</primary>
          </indexterm>
        </listitem>
      </varlistentry>
-->

      <varlistentry id="pkexec">
        <term><command>pkexec</command></term>
        <listitem>
          <para>
            allows an authorized user to execute a command as another user
          </para>
          <indexterm zone="polkit pkexec">
            <primary sortas="b-pkexec">pkexec</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="pkttyagent">
        <term><command>pkttyagent</command></term>
        <listitem>
          <para>
            is used to start a textual authentication agent for the subject
          </para>
          <indexterm zone="polkit pkttyagent">
            <primary sortas="b-pkttyagent">pkttyagent</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="polkitd">
        <term><command>polkitd</command></term>
        <listitem>
          <para>
            provides the org.freedesktop.PolicyKit1 <application>D-Bus</application>
            service on the system message bus
          </para>
          <indexterm zone="polkit polkitd">
            <primary sortas="b-polkitd">polkitd</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="libpolkit-agent-1">
        <term><filename class="libraryfile">libpolkit-agent-1.so</filename></term>
        <listitem>
          <para>
            contains the <application>Polkit</application> authentication
            agent API functions
          </para>
          <indexterm zone="polkit libpolkit-agent-1">
            <primary sortas="c-libpolkit-agent-1">libpolkit-agent-1.so</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="libpolkit-gobject-1">
        <term><filename class="libraryfile">libpolkit-gobject-1.so</filename></term>
        <listitem>
          <para>
            contains the <application>Polkit</application> authorization API functions
          </para>
          <indexterm zone="polkit libpolkit-gobject-1">
            <primary sortas="c-libpolkit-gobject-1">libpolkit-gobject-1.so</primary>
          </indexterm>
        </listitem>
      </varlistentry>

    </variablelist>

  </sect2>

</sect1>