From Fedora Project Wiki
(Created page with "= Usermode Migration = == Summary == <!-- A sentence or two summarizing what this feature is and what it will do. This information is used for the overall feature summary page ...")
 
(Feature accepted on Feb 13 FESCo meeting)
(35 intermediate revisions by 8 users not shown)
Line 2: Line 2:


== Summary ==
== Summary ==
<!-- A sentence or two summarizing what this feature is and what it will do.  This information is used for the overall feature summary page for each release. -->
Access control of privileged operations for ordinary users should be handled ''exclusively'' by a centrally managed authority.  
Migrate all applications depending on usermode to polkit.
 
Usermode/consolehelper should be phased out and be replaced entirely by polkit.


== Owner ==
== Owner ==
<!--This should link to your home wiki page so we know who you are-->
* Name: [[User:Harald| Harald Hoyer]]
* Name: [[User:harald| Harald Hoyer]]
* Email: harald@redhat.com


<!-- Include you email address that you can be reached should people want to contact you about helping with your feature, status is requested, or  technical issues need to be resolved-->
* Name: [[User:Kay| Kay Sievers]]
* Email: harald@redhat.com
* Email: kay@redhat.com
 
* Name: [[User: Notting| Bill Nottingham]]
* Email: notting@redhat.com


== Current status ==
== Current status ==
* Targeted release: [[Releases/18 | Fedora 18 ]]  
* Targeted release: [[Releases/19 | Fedora 19]]
* Last updated: 2012-04-03
* Last updated: 2012-10-16
* Percentage of completion: 0%
* Percentage of completion: 20%


== Detailed Description ==
== Detailed Description ==
<!-- Expand on the summary, if appropriate. A couple sentences suffices to explain the goal, but the more details you can provide the better. -->
The usermode/consolehelper program is a setuid-root wrapper around a couple of system tools, providing superuser privileges to ordinary users. Its policy is controlled by text files in /etc.
 
These days, most privileged system operations are already controlled by polkit, a well-established, fine-grained, (possibly) network-transparent service for managing privileged operations by ordinary users. Enterprise environments need to be able to centrally define access control policy for the organization, and automatically apply it to all connected workstations.
 
* polkit can be used by privileged processes to decide if it should execute privileged operations on behalf of the requesting user. For directly executed tools, polkit provides a setuid-root helper program called ‘’pkexec’’.The hooks to ask the user for authorizations are well-integrated into text environments, and native in all major graphical environments.
* The concept of a ''console user''  (that usermode/consolehelper implements) is no longer a sufficient concept to derive privileges from. OTOH polkit authorizations can properly distinguish between multiple active sessions and seats: e.g. an untrusted user’s reboot request is only granted if only a single user session runs at that time.
 
[http://www.freedesktop.org/software/polkit/docs/latest/polkit.8.html polkit(8) manual page]


== Benefit to Fedora ==
== Benefit to Fedora ==
<!-- What is the benefit to the platform?  If this is a major capability update, what has changed?  If this is a new feature, what capabilities does it bring? Why will Fedora become a better distribution or project because of this feature?-->
<!-- What is the benefit to the platform?  If this is a major capability update, what has changed?  If this is a new feature, what capabilities does it bring? Why will Fedora become a better distribution or project because of this feature?-->
* Consistency of system configuration.
* Centralization of policy.
* Cleaner system integration; no implicit interception of tools residing in sbin/ with symlinks in bin/, which is less dependent on $PATH ordering.
* No difference regarding the hookup between tools installed in bin/ or sbin/.


== Scope ==
== Scope ==
<!-- What work do the developers have to accomplish to complete the feature in time for release?  Is it a large change affecting many parts of the distribution or is it a very isolated change? What are those changes?-->
<!-- What work do the developers have to accomplish to complete the feature in time for release?  Is it a large change affecting many parts of the distribution or is it a very isolated change? What are those changes?-->
* Document how to convert consolehelper to polkit:
** python: put a pkexec invocation in the wrapping shell script
** C tools: re-exec with pkexec in C code
** C tools: move original to /usr/lib/<pkg>/<tool>, and wrap /usr/bin/<tool> with a pkexec shell script (ugly!)
* File bugs against all individual packages, and add them to tracker bug [https://bugzilla.redhat.com/show_bug.cgi?id=502765 502765]
* Convert all packages where it makes sense to use polkit to pkexec.
* If all packages are successfully converted, userhelper may be removed
=== How to Convert ===
A quick and easy way to convert a former consolehelper program is the use of pkexec.
As an example we convert system-config-date to polkit:
<pre>
# ls -l /usr/bin/system-config-date
lrwxrwxrwx 1 root root 13  5. Feb 02:34 /usr/bin/system-config-date -> consolehelper
# rm /usr/bin/system-config-date
# cat /etc/security/console.apps/system-config-date
. config-util
PROGRAM=/usr/share/system-config-date/system-config-date.py
SESSION=true
</pre>
OK, running /usr/bin/system-config-date would have executed /usr/share/system-config-date/system-config-date.py, so we create /usr/bin/system-config-date like the following:
<pre>
# cat /usr/bin/system-config-date
#!/bin/sh
exec /usr/bin/pkexec /usr/share/system-config-date/system-config-date.py
</pre>
This will not export the DISPLAY variable, so we have to add a policy file, although starting a GUI as root is not encouraged.
The important part is: <annotate key="org.freedesktop.policykit.exec.allow_gui">true</annotate>
<code>/usr/share/polkit-1/actions/org.fedoraproject.config.date.policy</code>:
<pre>
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE policyconfig PUBLIC
"-//freedesktop//DTD PolicyKit Policy Configuration 1.0//EN"
"http://www.freedesktop.org/standards/PolicyKit/1/policyconfig.dtd">
<policyconfig>
<vendor>System Config Date</vendor>
<vendor_url>http://fedorahosted.org/system-config-date</vendor_url>
<action id="org.fedoraproject.config.date.pkexec.run">
    <_description>Run System Config Date</_description>
    <_message>Authentication is required to run system-config-date</_message>
    <icon_name>system-config-date</icon_name>
    <defaults>
    <allow_any>no</allow_any>
    <allow_inactive>no</allow_inactive>
    <allow_active>auth_admin_keep</allow_active>
    </defaults>
    <annotate key="org.freedesktop.policykit.exec.path">/usr/share/system-config-date/system-config-date.py</annotate>
    <annotate key="org.freedesktop.policykit.exec.allow_gui">true</annotate>
</action>
</policyconfig>
</pre>


== How To Test ==
== How To Test ==
<!-- This does not need to be a full-fledged document.  Describe the dimensions of tests that this feature is expected to pass when it is done.  If it needs to be tested with different hardware or software configurations, indicate them.  The more specific you can be, the better the community testing can be.  
<pre>
# yum remove usermode usermode-gtk
</pre>
should succeed for an installation with all Fedora packages installed.


Remember that you are writing this how to for interested testers to use to check out your feature - documenting what you do for testing is OK, but it's much better to document what *I* can do to test your feature.
<pre>
# repoquery --whatrequires usermode --whatrequires usermode-gtk
usermode-gtk-....
</pre>
should not output a single package, except the usermode-gtk package.


A good "how to test" should answer these four questions:
Make sure you can call all the tools which used to use usermode and are asked the appropriate authentication.
 
0. What special hardware / data / etc. is needed (if any)?
1. How do I prepare my system to test this feature? What packages
need to be installed, config files edited, etc.?
2. What specific actions do I perform to check that the feature is
working like it's supposed to?
3. What are the expected results of those actions?
-->


== User Experience ==
== User Experience ==
<!-- If this feature is noticeable by its target audience, how will their experiences change as a result?  Describe what they will see or notice. -->
The user should experience no noticeable changes.


== Dependencies ==
== Dependencies ==
<!-- What other packages (RPMs) depend on this package?  Are there changes outside the developers' control on which completion of this feature depends?  In other words, completion of another feature owned by someone else and might cause you to not be able to finish on time or that you would need to coordinate?  Other upstream projects like the kernel (if this is not a kernel feature)? -->
<!-- What other packages (RPMs) depend on this package?  Are there changes outside the developers' control on which completion of this feature depends?  In other words, completion of another feature owned by someone else and might cause you to not be able to finish on time or that you would need to coordinate?  Other upstream projects like the kernel (if this is not a kernel feature)? -->
* anaconda
* audit-viewer
* authconfig-gtk
* backintime-gnome
* backintime-kde
* beesu
* bootconf-gui
* chkrootkit
* driftnet
* drobo-utils-gui
* eclipse-oprofile
* ejabberd
* fwfstab
* galternatives
* gsmartcontrol
* hddtemp
* kdenetwork-kppp
* kismet
* liveusb-creator
* livna-config-display
* lshw-gui
* mock
* mtr-gtk
* netgo
* nmap-frontend
* ntfs-config
* policycoreutils-gui
* preupgrade
* pure-ftpd
* qtparted
* realcrypt
* revisor-cli
* rhn-setup
* rhn-setup-gnome
* sabayon
* setools-gui
* setuptool
* smart-gui
* subscription-manager-gnome
* synaptic
* system-config-audit
* system-config-bind
* system-config-boot
* system-config-date
* system-config-httpd
* system-config-kdump
* system-config-keyboard
* system-config-language
* system-config-lvm
* system-config-network
* system-config-network-tui
* system-config-nfs
* system-config-rootpassword
* system-config-users
* system-switch-displaymanager
* system-switch-java
* system-switch-mail
* system-switch-mail-gnome
* tuned
* usermode-gtk
* vpnc-consoleuser
* wifi-radar
* wlassistant
* xawtv
* yumex
* zyx-liveinstaller


== Contingency Plan ==
== Contingency Plan ==
<!-- If you cannot complete your feature by the final development freeze, what is the backup plan?  This might be as simple as "None necessary, revert to previous release behaviour."  Or it might not.  If you feature is not completed in time we want to assure others that other parts of Fedora will not be in jeopardy.  -->
<!-- If you cannot complete your feature by the final development freeze, what is the backup plan?  This might be as simple as "None necessary, revert to previous release behaviour."  Or it might not.  If you feature is not completed in time we want to assure others that other parts of Fedora will not be in jeopardy.  -->
Even if we cannot drop usermode for F19 (because not all packages have been converted) the changes in the packages do not have to be reverted.


== Documentation ==
== Documentation ==
<!-- Is there upstream documentation on this feature, or notes you have written yourself?  Link to that material here so other interested developers can get involved. -->
* [http://www.freedesktop.org/wiki/Software/polkit polkit Homepage]
*
* [http://www.freedesktop.org/software/polkit/docs/latest/ polkit Documentation]
* [http://www.freedesktop.org/software/polkit/docs/latest/polkit.8.html polkit(8) manpage]
* [http://www.freedesktop.org/software/polkit/docs/latest/pkexec.1.html pkexec(1) manpage]


== Release Notes ==
== Release Notes ==
<!-- The Fedora Release Notes inform end-users about what is new in the release. Examples of past release notes are here: http://docs.fedoraproject.org/release-notes/ -->
 
<!-- The release notes also help users know how to deal with platform changes such as ABIs/APIs, configuration or data file formats, or upgrade concerns.  If there are any such changes involved in this feature, indicate them here.  You can also link to upstream documentation if it satisfies this need.  This information forms the basis of the release notes edited by the documentation team and shipped with the release. -->
* The following packages now use the polkit policy configuration instead of the usermode/consolehelper configuration. Please migrate any policy, which you have created for those packages. Documentation about polkit can be found on http://www.freedesktop.org/software/polkit/docs/latest/
*
 
  <list of packages>


== Comments and Discussion ==
== Comments and Discussion ==
* See [[Talk:Features/UsermodeMigration]] <!-- This adds a link to the "discussion" tab associated with your page.  This provides the ability to have ongoing comments or conversation without bogging down the main feature page -->
* See [[Talk:Features/UsermodeMigration]]
 


[[Category:FeaturePageIncomplete]]
[[Category:FeatureAcceptedF19]]
<!-- When your feature page is completed and ready for review -->
<!-- When your feature page is completed and ready for review -->
<!-- remove Category:FeaturePageIncomplete and change it to Category:FeatureReadyForWrangler -->
<!-- remove Category:FeaturePageIncomplete and change it to Category:FeatureReadyForWrangler -->
<!-- After review, the feature wrangler will move your page to Category:FeatureReadyForFesco... if it still needs more work it will move back to Category:FeaturePageIncomplete-->
<!-- After review, the feature wrangler will move your page to Category:FeatureReadyForFesco... if it still needs more work it will move back to Category:FeaturePageIncomplete-->
<!-- A pretty picture of the page category usage is at: https://fedoraproject.org/wiki/Features/Policy/Process -->
<!-- A pretty picture of the page category usage is at: https://fedoraproject.org/wiki/Features/Policy/Process -->

Revision as of 10:01, 15 February 2013

Usermode Migration

Summary

Access control of privileged operations for ordinary users should be handled exclusively by a centrally managed authority.

Usermode/consolehelper should be phased out and be replaced entirely by polkit.

Owner

Current status

  • Targeted release: Fedora 19
  • Last updated: 2012-10-16
  • Percentage of completion: 20%

Detailed Description

The usermode/consolehelper program is a setuid-root wrapper around a couple of system tools, providing superuser privileges to ordinary users. Its policy is controlled by text files in /etc.

These days, most privileged system operations are already controlled by polkit, a well-established, fine-grained, (possibly) network-transparent service for managing privileged operations by ordinary users. Enterprise environments need to be able to centrally define access control policy for the organization, and automatically apply it to all connected workstations.

  • polkit can be used by privileged processes to decide if it should execute privileged operations on behalf of the requesting user. For directly executed tools, polkit provides a setuid-root helper program called ‘’pkexec’’.The hooks to ask the user for authorizations are well-integrated into text environments, and native in all major graphical environments.
  • The concept of a console user (that usermode/consolehelper implements) is no longer a sufficient concept to derive privileges from. OTOH polkit authorizations can properly distinguish between multiple active sessions and seats: e.g. an untrusted user’s reboot request is only granted if only a single user session runs at that time.

polkit(8) manual page

Benefit to Fedora

  • Consistency of system configuration.
  • Centralization of policy.
  • Cleaner system integration; no implicit interception of tools residing in sbin/ with symlinks in bin/, which is less dependent on $PATH ordering.
  • No difference regarding the hookup between tools installed in bin/ or sbin/.

Scope

  • Document how to convert consolehelper to polkit:
    • python: put a pkexec invocation in the wrapping shell script
    • C tools: re-exec with pkexec in C code
    • C tools: move original to /usr/lib/<pkg>/<tool>, and wrap /usr/bin/<tool> with a pkexec shell script (ugly!)
  • File bugs against all individual packages, and add them to tracker bug 502765
  • Convert all packages where it makes sense to use polkit to pkexec.
  • If all packages are successfully converted, userhelper may be removed

How to Convert

A quick and easy way to convert a former consolehelper program is the use of pkexec.

As an example we convert system-config-date to polkit: 

# ls -l /usr/bin/system-config-date
lrwxrwxrwx 1 root root 13  5. Feb 02:34 /usr/bin/system-config-date -> consolehelper

# rm /usr/bin/system-config-date
# cat /etc/security/console.apps/system-config-date
. config-util
PROGRAM=/usr/share/system-config-date/system-config-date.py
SESSION=true

OK, running /usr/bin/system-config-date would have executed /usr/share/system-config-date/system-config-date.py, so we create /usr/bin/system-config-date like the following: 

# cat /usr/bin/system-config-date
#!/bin/sh
exec /usr/bin/pkexec /usr/share/system-config-date/system-config-date.py

This will not export the DISPLAY variable, so we have to add a policy file, although starting a GUI as root is not encouraged. The important part is: <annotate key="org.freedesktop.policykit.exec.allow_gui">true</annotate>

/usr/share/polkit-1/actions/org.fedoraproject.config.date.policy: 

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE policyconfig PUBLIC
"-//freedesktop//DTD PolicyKit Policy Configuration 1.0//EN"
"http://www.freedesktop.org/standards/PolicyKit/1/policyconfig.dtd">
<policyconfig>

 <vendor>System Config Date</vendor>
 <vendor_url>http://fedorahosted.org/system-config-date</vendor_url>

 <action id="org.fedoraproject.config.date.pkexec.run">
    <_description>Run System Config Date</_description>
    <_message>Authentication is required to run system-config-date</_message>
    <icon_name>system-config-date</icon_name>
    <defaults>
     <allow_any>no</allow_any>
     <allow_inactive>no</allow_inactive>
     <allow_active>auth_admin_keep</allow_active>
    </defaults>
    <annotate key="org.freedesktop.policykit.exec.path">/usr/share/system-config-date/system-config-date.py</annotate>
    <annotate key="org.freedesktop.policykit.exec.allow_gui">true</annotate>
 </action>
</policyconfig>

How To Test

# yum remove usermode usermode-gtk

should succeed for an installation with all Fedora packages installed. 

# repoquery --whatrequires usermode --whatrequires usermode-gtk
usermode-gtk-....

should not output a single package, except the usermode-gtk package.

Make sure you can call all the tools which used to use usermode and are asked the appropriate authentication.

User Experience

The user should experience no noticeable changes.

Dependencies

  • anaconda
  • audit-viewer
  • authconfig-gtk
  • backintime-gnome
  • backintime-kde
  • beesu
  • bootconf-gui
  • chkrootkit
  • driftnet
  • drobo-utils-gui
  • eclipse-oprofile
  • ejabberd
  • fwfstab
  • galternatives
  • gsmartcontrol
  • hddtemp
  • kdenetwork-kppp
  • kismet
  • liveusb-creator
  • livna-config-display
  • lshw-gui
  • mock
  • mtr-gtk
  • netgo
  • nmap-frontend
  • ntfs-config
  • policycoreutils-gui
  • preupgrade
  • pure-ftpd
  • qtparted
  • realcrypt
  • revisor-cli
  • rhn-setup
  • rhn-setup-gnome
  • sabayon
  • setools-gui
  • setuptool
  • smart-gui
  • subscription-manager-gnome
  • synaptic
  • system-config-audit
  • system-config-bind
  • system-config-boot
  • system-config-date
  • system-config-httpd
  • system-config-kdump
  • system-config-keyboard
  • system-config-language
  • system-config-lvm
  • system-config-network
  • system-config-network-tui
  • system-config-nfs
  • system-config-rootpassword
  • system-config-users
  • system-switch-displaymanager
  • system-switch-java
  • system-switch-mail
  • system-switch-mail-gnome
  • tuned
  • usermode-gtk
  • vpnc-consoleuser
  • wifi-radar
  • wlassistant
  • xawtv
  • yumex
  • zyx-liveinstaller

Contingency Plan

Even if we cannot drop usermode for F19 (because not all packages have been converted) the changes in the packages do not have to be reverted.

Documentation

Release Notes

  • The following packages now use the polkit policy configuration instead of the usermode/consolehelper configuration. Please migrate any policy, which you have created for those packages. Documentation about polkit can be found on http://www.freedesktop.org/software/polkit/docs/latest/
 <list of packages>

Comments and Discussion

Retrieved from "https://fedoraproject.org/w/index.php?title=Features/UsermodeMigration&oldid=323525"