pklocalauthority(8)
NAME
pklocalauthority - PolicyKit Local Authority
DESCRIPTION
The Local Authority is the default PolicyKit authority implementation. Configuration for the Local Authority and information pertaining to authorization decisions are read from local files on the disk. One design goal of the Local Authority is to split configuration items into separate files such that 3rd party packages and users won't conflict trying to edit the same files. This policy also ensures smooth upgrades when distributing PolicyKit using a package management system. Files shipped with PolicyKit and 3rd party packages (e.g. under package manager control) typically have comments (such as "DO NOT EDIT THIS FILE, it will be overwritten on update") telling the system administrator that changes will be overwritten on update.
ADMINISTRATOR AUTHENTICATION
PolicyKit makes a distinction between user authentication (to make the user in front of the system prove he really is the user) and administrator authentication (to make the user in front of the system prove he really is an administrator). Since various operating systems (or even flavors of the same operating system) has different ways of defining "administrator", the Local Authority provides a way to specify what "administrator authentication" means. By default, "administrator authentication" is defined as asking for the root password. Since some systems, for usability reasons, don't have a root password and instead rely on a group of users being member of an administrative group that gives them super-user privileges, the Local Authority can be configured to support this use-case as well. Configuration for the Local Authority is read from files in the /etc/polkit-1/localauthority.conf.d directory. All files are read in lexigraphical order (using the C locale) meaning that later files can override earlier ones. The file 50-localauthority.conf contains the settings provided by the OS vendor. Users and 3rd party packages can drop configuration files with a priority higher than 60 to change the defaults. The configuration file format is simple. Each configuration file is a key file (also commonly known as a ini file) with a single group called [Configuration]. Only a single key, AdminIdentities is read. The value of this key is a semi-colon separated list of identities that can be used when administrator authentication is required. Users are specified by prefixing the user name with unix-user:, groups of users are specified by prefixing with unix-group:, and netgroups of users are specified with unix-netgroup:. See the section called "EXAMPLES" for an example of a configuration file.
DIRECTORY STRUCTURE
The Local Authority reads files with .pkla extension from all
directories located inside the /etc/polkit-1/localauthority and
/var/lib/polkit-1/localauthority directories. By default, the following
sub-directories are installed.
/etc/polkit-1/
`-- localauthority
|-- 10-vendor.d
|-- 20-org.d
|-- 30-site.d
|-- 50-local.d
`-- 90-mandatory.d
and
/var/lib/polkit-1/
`-- localauthority
|-- 10-vendor.d
|-- 20-org.d
|-- 30-site.d
|-- 50-local.d
`-- 90-mandatory.d
The /etc/polkit-1/localauthority hierarchy is inteded for local
configuration and the /var/lib/polkit-1/localauthority is intended for
3rd party packages.
Each .pkla file contains one or more authorization entries. If the
underlying filesystem supports file monitoring, the Local Authority
will reload information whenever .pkla files are added, removed or
changed.
Each directory is intended for a specific audience
10-vendor.d
Intended for use by the OS vendor.
20-org.d
Intended for the organization deploying the OS.
30-site.d
Intended for the site deploying the system.
50-local.d
Intended for local usage.
90-mandatory.d
Intended for the organization deploying the OS.
and new directories can be added/removed as needed.
As to regards to the content, each .pkla file is a standard key file
and contains key/value pairs in one or more groups with each group
representing an authorization entry. A .pkla file MUST be named by
using a scheme to ensure that the name is unique, e.g. reverse DNS
notation or similar. For example, if the organization is "Acme Corp"
needs to modify policy for the product "Frobnicator", a name like
com.acme.frobnicator.pkla would be suitable.
AUTHORIZATION ENTRY
Each group in a .pkla file must have a name that is unique within the
file it belongs to. The following keys are are recognized:
Identity
A semi-colon separated list of globs to match identities. Each glob
should start with unix-user: or unix-group: to specify whether to
match on a UNIX user name or a UNIX group name. Netgroups are
supported with the unix-netgroup: prefix, but cannot support glob
syntax.
Action
A semi-colon separated list of globs to match action identifiers.
ResultActive
The result to return for subjects in an active local session that
matches one or more of the given identities. Allowed values are
similar to what can be used in the defaults section of .policy
files used to define actions, e.g. yes, no, auth_self,
auth_self_keep, auth_admin and auth_admin_keep.
ResultInactive
Like ResultActive but instead applies to subjects in inactive local
sessions.
ResultAny
Like ResultActive but instead applies to any subject.
ReturnValue
A semi-colon separated list of key/value pairs (of the form
key=value) that are added to the details of authorization result on
positive matches.
All keys specified above are required except that only at least one of
ResultAny, ResultInactive and ResultActive must be present. The
ReturnValue key is optional.
EVALUATION ORDER
When a Mechanism requests services from the Authority to check if a
given Subject is authorized for a given Action, the authorization
entries discussed above are consulted using the following algorithm.
The authorization entries from all .pkla files are ordered using the
following rules. First all the basename of all sub-directories (e.g.
30-site.d) from both the /etc/polkit-1/localauthority and
/var/lib/polkit-1/localauthority directories are enumerated and sorted
(using the C locale). If a name exists in both /etc and /var, the one
in /etc takes precedence. Then all .pkla files are read in order from
this list of sub-directories. For each .pkla file, authorizations from
each file are appended in order resulting in an ordered list of
authorization entries.
For example, given the following files
/var/lib/polkit-1
localauthority
10-vendor.d
10-desktop-policy.pkla
20-org.d
30-site.d
50-local.d
55-org.my.company.d
10-org.my.company.product.pkla
90-mandatory.d
/etc/polkit-1
localauthority
10-vendor.d
01-some-changes-from-a-subvendor.pkla
20-org.d
30-site.d
50-local.d
55-org.my.company.d
10-org.my.company.product.pkla
90-mandatory.d
the evaluation order of the .pkla files is:
1. 10-desktop-policy.pkla
2. 01-some-changes-from-a-subvendor.pkla
3. 10-org.my.company.product.pkla (the /var one)
4. 10-org.my.company.product.pkla (the /etc one)
When the list of authorization entries has been calculated, the
authorization check can be made. First, the user of the Subject is
determined and the groups that the user belongs are looked up. For each
group identity, the authorization entries are consulted in order. If
the authorization check matches the data from the authorization check,
then the authorization result from RequireAny, RequireInactive or
RequireActive is used and ReturnValue is added to the authorization
result.
Finally, the authorization entries are consulted using the user
identity in the same manner.
Note that processing continues even after a match. This allows for
socalled "negative authorizations", see the section called "EXAMPLES"
for further discussion.
EXAMPLES
The following .conf file
[Configuration]
AdminIdentities=unix-group:staff
specifies that any user in the staff UNIX group can be used for
authentication when administrator authentication is needed. This file
would typically be installed in the /etc/polkit-1/localauthority.conf.d
directory and given the name 60-desktop-policy.conf to ensure that it
is evaluted after the 50-localauthority.conf file shipped with
PolicyKit. If the local administrator wants to override this (suppose
60-desktop-policy.conf was shipped as part of the OS) he can simply
create a file 99-my-admin-configuration.conf with the following content
[Configuration]
AdminIdentities=unix-user:lisa;unix-user:marge
to specify that only the users lisa and marge can authenticate when
administrator authentication is needed.
The following .pkla file grants authorization to all users in the staff
group for actions matching the glob com.example.awesomeproduct.*
provided they are in an active session on the local console:
[Normal Staff Permissions]
Identity=unix-group:staff
Action=com.example.awesomeproduct.*
ResultAny=no
ResultInactive=no
ResultActive=yes
If the users homer and grimes are member of the staff group but policy
requires that an administrator needs to authenticate every time
authorization for any action matching com.example.awesomeproduct.* is
required, one would add
[Exclude Some Problematic Users]
Identity=unix-user:homer;unix-user:grimes
Action=com.example.awesomeproduct.*
ResultAny=no
ResultInactive=no
ResultActive=auth_admin
and make sure this authorization entry is after the first one.
AUTHOR
Written by David Zeuthen <davidz@redhat.com> with a lot of help from many others.
BUGS
Please send bug reports to either the distribution or the polkit-devel mailing list, see the link http://lists.freedesktop.org/mailman/listinfo/polkit-devel on how to subscribe.
SEE ALSO
polkit(8)
Opportunity
Personal Opportunity - Free software gives you access to billions of dollars of software at no cost. Use this software for your business, personal use or to develop a profitable skill. Access to source code provides access to a level of capabilities/information that companies protect though copyrights. Open source is a core component of the Internet and it is available to you. Leverage the billions of dollars in resources and capabilities to build a career, establish a business or change the world. The potential is endless for those who understand the opportunity.
Business Opportunity - Goldman Sachs, IBM and countless large corporations are leveraging open source to reduce costs, develop products and increase their bottom lines. Learn what these companies know about open source and how open source can give you the advantage.
Free Software
Free Software provides computer programs and capabilities at no cost but more importantly, it provides the freedom to run, edit, contribute to, and share the software. The importance of free software is a matter of access, not price. Software at no cost is a benefit but ownership rights to the software and source code is far more significant.
Free Office Software - The Libre Office suite provides top desktop productivity tools for free. This includes, a word processor, spreadsheet, presentation engine, drawing and flowcharting, database and math applications. Libre Office is available for Linux or Windows.
Free Books
The Free Books Library is a collection of thousands of the most popular public domain books in an online readable format. The collection includes great classical literature and more recent works where the U.S. copyright has expired. These books are yours to read and use without restrictions.
Source Code - Want to change a program or know how it works? Open Source provides the source code for its programs so that anyone can use, modify or learn how to write those programs themselves. Visit the GNU source code repositories to download the source.
Education
Study at Harvard, Stanford or MIT - Open edX provides free online courses from Harvard, MIT, Columbia, UC Berkeley and other top Universities. Hundreds of courses for almost all major subjects and course levels. Open edx also offers some paid courses and selected certifications.
Linux Manual Pages - A man or manual page is a form of software documentation found on Linux/Unix operating systems. Topics covered include computer programs (including library and system calls), formal standards and conventions, and even abstract concepts.
