Skip to content

Latest commit

 

History

History
629 lines (368 loc) · 15.8 KB

REFERENCE.md

File metadata and controls

629 lines (368 loc) · 15.8 KB
Raw

Reference

Table of Contents

Classes

Defined types

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

Classes

polkit

Allows you to set up and manipulate PolicyKit objects

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: 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',
  ]]