This is a SIMP module

This module is a component of the System Integrity Management Platform, a compliance-management framework built on Puppet.

If you find any issues, they can be submitted to our JIRA.

Please read our Contribution Guide.

Module Description

This module provides for the configuration of polkit policies.

Reference

Plesae see REFERENCE.md for details.

Development

Please read our Contribution Guide.

Visit the project homepage and look at our issues on JIRA.

Reference

Table of Contents

Classes

• polkit: Set up PolicyKit
• polkit::install: Manage the polkit package
• polkit::service: Ensure that the polkit service is running
• polkit::user: Manage the polkit user
• polkit::user::hidepid_notify: A notification for hidepid user creation

Defined types

• polkit::authorization::basic_policy: Add a rule file containing javascript Polkit configuration to the system
• polkit::authorization::rule: Add a rule file containing javascript Polkit configuration to the system
• polkit::local_authority: Add PolicyKit Local Authority policies to a system Only the default authority directories are currently supported

Functions

• polkit::validate_identity: Validate that all entries are valid PolicyKit identities per pkla-check-authorization(8). Abort catalog compilation if any entry fails this

Data types

• Polkit::Authority: polkit authority types
• Polkit::PackageEnsure: Package ensure type
• Polkit::Result: Polkit result types

Classes

polkit

Allows you to set up and manipulate PolicyKit objects

• See also
  • http://www.freedesktop.org/software/polkit/docs/latest/
    • PolicyKit Documentation

Parameters

The following parameters are available in the polkit class.

manage_polkit_user

Data type: Boolean

Enables managment of the $polkit_user

• Enabled by default since newer versions of polkit require the $polkit_user to be in the group assigned to /proc to function properly

@see polkit::user

Default value: true

package_ensure

Data type: Polkit::PackageEnsure

The ensure status of packages

Default value: simplib::lookup('simp_options::package_ensure', { 'default_value' => 'installed' })

warn_on_unsupported_os

Data type: Boolean

Warn if the module is trying to be used on an unsupported OS

• The module will not fail on an unsupported OS but also will not perform any action

Default value: true

polkit::install

Manage the polkit package

Parameters

The following parameters are available in the polkit::install class.

package_name

Data type: String[1]

The name of the package to manage

Default value: 'polkit'

package_ensure

Data type: Variant[String[1],Boolean]

ensure state from the service resource

Default value: $polkit::package_ensure

polkit::service

Ensure that the polkit service is running

Parameters

The following parameters are available in the polkit::service class.

ensure

Data type: Variant[String[1],Boolean]

ensure state from the service resource

Default value: 'running'

enable

Data type: Boolean

enable state from the service resource

Default value: true

service_name

Data type: String[1]

The name of the service to manage

Default value: 'polkit'

polkit::user

Manage the polkit user

Parameters

The following parameters are available in the polkit::user class.

user

Data type: String[1]

The user that polkit runs as

Default value: 'polkitd'

user_options

Data type: Hash

Allows setting of any of the usual puppet User resource options. Will have the GID assigned to /proc added to the groups to preserve proper system functionality.

Default value: {}

report_proc_issues

Data type: Boolean

Actively notify the user about issues with the hidepid setting on the /proc filesystem

Default value: true

polkit::user::hidepid_notify

This was moved into a separate class for resource notification chaining correctness

Parameters

The following parameters are available in the polkit::user::hidepid_notify class.

log_level

Data type: Any

The log level to use when generating the notification message

Default value: 'warning'

Defined types

polkit::authorization::basic_policy

The intention of this define is to make it easy to add simple polkit rules to a system. An example simple rule template is shown below:

// This file is managed by Puppet
polkit.addRule(function(action, subject) {
  if (<condition>) {
      return polkit.Result.<result>;
    }
  }
});

A user-specified can be supplied with the $condition parameter, or the define can use the polkit::condition function to generate a condition using $action_id, $user and/or $group, an (optionally) $local and $active.

• See also
  • polkit(8)

Examples

Allow users in the virtusers group to use the system libvirt

polkit::authorization::basic_policy { 'Allow users to use libvirt':
  ensure    => present,
  group     => 'virtusers',
  result    => 'yes'
  action_id => 'org.libvirt.unix.manage',
  priority  => 20,
  local     => true,
  active    => true,
}

# Generates a policy file that looks like this
// This file is managed by Puppet
polkit.addRule(function(action, subject) {
  if ((action.id == 'org.libvirt.unix.manage') && subject.user == 'testuser' && subject.isInGroup('testgroup') && subject.local && subject.active) {
      return polkit.Result.YES;
    }
  }
});

Parameters

The following parameters are available in the polkit::authorization::basic_policy defined type.

ensure

Data type: Enum['present','absent']

Create or destroy the rules file

Default value: 'present'

result

Data type: Polkit::Result

The authorization result of the polkit transaction, for example yes or auth_admin

action_id

Data type: Optional[String]

The polkit action to operate on

• A list of available actions can be found by running pkaction

Default value: undef

user

Data type: Variant[Undef,String,Array[String]]

User to check

Default value: undef

group

Data type: Variant[Undef,String,Array[String]]

The group(s) that the user checking authorization belongs to

Default value: undef

local

Data type: Boolean

Check if the user is a local user. See man page for more explaination

Default value: false

active

Data type: Boolean

Check if the user is currently active. See man page for more explaination

Default value: false

condition

Data type: Optional[String]

If specified, will be placed in the javascript condition to be met for polkit authorization

Default value: undef

log_action

Data type: Boolean

Log the action to the system log

Default value: true

log_subject

Data type: Boolean

Log the subject to the system log

Default value: true

priority

Data type: Integer[0,99]

Priority of the file to be created

Default value: 10

rulesd

Data type: Stdlib::AbsolutePath

Location of the poklit rules directory

Default value: '/etc/polkit-1/rules.d'

polkit::authorization::rule

Add a rule file containing javascript Polkit configuration to the system

Parameters

The following parameters are available in the polkit::authorization::rule defined type.

ensure

Data type: Enum['present','absent']

Create or destroy the rules file

content

Data type: Optional[String]

An arbitrary string of javascript polkit configuration

priority

Data type: Integer[0,99]

Priority of the file to be created, lower priority means the rule would be read earlier

Default value: 10

rulesd

Data type: Stdlib::AbsolutePath

Location of the poklit rules directory

Default value: '/etc/polkit-1/rules.d'

polkit::local_authority

Add PolicyKit Local Authority policies to a system

Only the default authority directories are currently supported

• See also
  • pklocalauthority(8)

Examples

Local Test Policy

polkit::local_authority { 'test_policy':
  identity        => 'unix-group:staff',
  action          => 'com.example.awesomeproduct.*',
  result_any      => 'no',
  result_inactive => 'no',
  result_active   => 'auth_admin'
}

Parameters

The following parameters are available in the polkit::local_authority defined type.

name

A descriptive, valid filename (not path) in which to house your pkla entries

• Do not include the leading number or the trailing .pkla

identity

Data type: Variant[String,Array[String]]

Identities as designated by pkla-check-authorization(8)

Single entries may be entered as a String. Multiple entries should be represented as an Array of entries and NOT a semicolon separated string.

action

Data type: String

ensure

Data type: Enum['file','absent','present']

This passes directly down to the file type but only cares if you set it to absent

Default value: 'present'

target_directory

Data type: Stdlib::Absolutepath

The destination base directory for your pkla file

• Anything may be used, but logical values are:
  • /etc/polkit-1/localauthority
  • /var/lib/polkit-1/localauthority

Default value: '/etc/polkit-1/localauthority'

authority

Data type: Polkit::Authority

The local authority directory in which to store the pkla file

Supported values are:

• local
• mandatory
• org
• site
• vendor

Default value: 'mandatory'

order

Data type: Integer

The order number given to your pkla file

• Higher numbers override lower ones in alphanumeric order

Default value: 50

section_name

Data type: String

The section name within the pkla file

Default value: $name

result_active

Data type: Polkit::Result

Default value: undef

result_inactive

Data type: Polkit::Result

Default value: undef

result_any

Data type: Polkit::Result

Default value: undef

return_value

Data type: Polkit::Result

Default value: undef

Functions

polkit::validate_identity

Type: Ruby 4.x API

Validate that all entries are valid PolicyKit identities per pkla-check-authorization(8). Abort catalog compilation if any entry fails this check.

polkit::validate_identity(String $identity)

The polkit::validate_identity function.

Returns: Any None

identity

Data type: String

Polkit identity; must begin with a 'unix-user:' or 'unix_group:' header; the value portion can contain a wildcard. For example, 'unix-user:username' or 'unix-group:mygroup*'

polkit::validate_identity(Array[String] $identities)

The polkit::validate_identity function.

Returns: Any None

identities

Data type: Array[String]

Array of Polkit identities; each must begin with a 'unix-user:' or 'unix_group:' header; each value portion can contain a wildcard.

Data types

Polkit::Authority

polkit authority types

Alias of Enum['vendor', 'org', 'site', 'local', 'mandatory']

Polkit::PackageEnsure

Package ensure type

Alias of Variant[String, Enum[ 'latest', 'installed', 'absent', 'purged' ]]

Polkit::Result

Polkit result types

Alias of Optional[Enum[ 'yes', 'no', 'auth_self', 'auth_self_keep', 'auth_admin', 'auth_admin_keep', ]]

• Wed Jun 16 2021 Chris Tessmer chris.tessmer@onyxpoint.com - 6.4.0

• Removed support for Puppet 5
• Ensured support for Puppet 7 in requirements and stdlib

• Sat Dec 19 2020 Chris Tessmer chris.tessmer@onyxpoint.com - 6.3.1

• Removed EL6 support

• Wed Sep 02 2020 Trevor Vaughan tvaughan@onyxpoint.com - 6.3.0-0

• Added the following classes
  • polkit::install
  • polkit::service
  • polkit::user
• Ensure that the polkit user is managed by default and placed into the supplementary group bound to the 'gid' option on '/proc' if one is set to work around issues with 'hidepid' > 0.
• Made the entire main class inert on unsupported OSs and log a warning on the server that can be disabled

• Tue Dec 24 2019 Trevor Vaughan tvaughan@onyxpoint.com - 6.2.0-0

• Add EL8 support
• Drop EL6 support (it was non-functional)
• Fix issue with basic_policy template that resulted in malformed rules
• Add acceptance tests

• Fri Aug 02 2019 Robert Vincent pillarsdotnet@gmail.com - 6.2.0-0

• Drop Puppet 4 support
• Add Puppet 6 support
• Add puppetlabs-stdlib 6 support

• Thu Mar 07 2019 Liz Nemsick lnemsick.simp@gmail.com - 6.1.2-0

• Update the upper bound of stdlib to < 6.0.0
• Update a URL in the README.md

• Sat Mar 24 2018 Trevor Vaughan tvaughan@onyxpoint.com - 6.1.1-0

• Add support for OEL and Puppet 5
• Update badges and contribution guide URL in README.md

• Wed Jun 21 2017 Liz Nemsick lnemsick.simp@gmail.com - 6.1.0-0

• Update custom Puppet 3 functions to namespaced, Puppet 4 functions
• Allow default identity and identities prefixed with unix-netgroup.
• Confine puppet version in metadata.json

• Mon Apr 17 2017 Nick Miller nick.miller@onyxpoint.com - 6.1.0-0

• Add EL7 and polkit 106+ support by allowing javascript rules
  • Added define to allow for easy placement of custom rules
  • Added templated define to ease generation of basic rules

• Mon Dec 19 2016 Jeanne Greulich jeanne.greulich@onyxpoint.com - 6.0.0-0

• Strong Typing
• Code cleanup

• Tue Nov 22 2016 Jeanne Greulich jeanne.greulich@onyxpoint.com - 5.0.0-0

• Major version bump for SIMP 6

• Mon Nov 21 2016 Chris Tessmer chris.tessmer@onypoint.com - 4.1.2-0

• Remove compliance_map and general housekeeping

• Mon Nov 09 2015 Chris Tessmer chris.tessmer@onypoint.com - 4.1.0-2

• migration to simplib and simpcat (lib/ only)

• Fri Jan 16 2015 Trevor Vaughan tvaughan@onyxpoint.com - 4.1.0-1

• Changed puppet-server requirement to puppet

• Tue Apr 08 2014 Kendall Moore kmoore@keywcorp.com - 4.1.0-0

• Refactored manifests to pass all lint tests for puppet 3 and hiera compatibility.
• Added spec tests.

• Mon Oct 07 2013 Kendall Moore kmoore@keywcorp.com - 4.0.0-3

• Updated all erb templates to properly scope variables.

• Thu Jul 04 2013 Trevor Vaughan tvaughan@onyxpoint.com - 4.0.0-2

• There was a bug in the 'identity' variable for polkit::local_authority where it would not properly accept arrays of users or groups.

• Mon Dec 31 2012 Trevor Vaughan tvaughan@onyxpoint.com - 4.0.0-1

• Created a Cucumber test that includes module in manifest and checks for config files.

• Fri Oct 26 2012 Trevor Vaughan tvaughan@onyxpoint.com - 4.0.0-0

• Initial module release