posix_acl

Table of Contents

1. Description
2. Setup

• Beginning with posix_acl

3. Usage

• Using action => set
• Using action => exact
• Using action => unset
• Using action => purge
• Using ignore_missing

7. Limitations
8. Transfer Notice
9. Contributions

Description

This plugin module provides a way to set POSIX 1.e (and other standards) file ACLs via Puppet. It provides one class, posix_acl::requirements, which installs the acl package. It provides setfacl and getfacl. Those binaries are used by the Puppet Provider. You don't have to use the class, but the binaries need to be present. Puppet will autorequire the package. That means that all posix_acl resources will be applied after the acl package is installed, if the package resource is in the catalog.

The type also has logic to autorequire filepaths. It will check the catalog for the path where you want to set ACLs and any paths above. If recursive is set to true, also ascendings paths are autorequired.

Setup

Beginning with posix_acl

• The posix_acl resource title is used as the path specifier.
• ACLs are specified in the permission property as an array of strings in the same format as is used for setfacl.
• The action parameter can be one of set, exact, unset or purge. These are described in detail below.
• The provider parameter allows a choice of filesystem ACL provider. Currently only POSIX 1.e is implemented.
• The recursive parameter allows you to apply the ACLs to all files under the specified path.
• The ignore_missing parameter allows you to set the behavior in case the specified path is not found.

posix_acl { "/var/log/httpd":
  action     => set,
  permission => [
    "user::rwx",
    "group::---",
    "mask::r-x",
    "other::---",
    "group:logview:r-x",
    "default:user::rwx",
    "default:group::---",
    "default:mask::rwx",
    "default:other::---",
    "default:group:logview:r-x",
  ],
  provider   => posixacl,
  require    => [
    Group["logview"],
    Package["httpd"],
    Mount["/var"],
  ],
  recursive  => false,
}

Usage

Using action => set

The set option for the action parameter allows you to specify a minimal set of ACLs which will be guaranteed by Puppet. ACLs applied to the path which do not match those specified in the permission property will remain unchanged.

Initial permissions

# file /var/www/site1
user::rwx
group::r-x
other::r-x
mask::rwx
group:webadmin:r-x
group:httpadmin:rwx

Specified acls

permission  => [
  'user::rwx',
  'group::r-x',
  'other::r-x',
  'mask::rwx',
  'group:webadmin:rwx',
  'user:apache:rwx',
],

Updated permissions

# file /var/www/site1
user::rwx
group::r-x
other::r-x
mask::rwx
user:apache:rwx
group:webadmin:rwx
group:httpadmin:rwx

Using action => exact

The exact option for the action parameter will specify the exact set of ACLs guaranteed and enforced by Puppet. ACLs applied to the path which do not match those specified in the permission property will be removed.

Initial permissions

# file /var/www/site1
user::rwx
group::r-x
other::r-x
mask::rwx
group:webadmin:r-x
group:httpadmin:rwx

Specified acls

permission  => [
  'user::rwx',
  'group::r-x',
  'other::r-x',
  'mask::rwx',
  'group:webadmin:r--',
  'user:apache:rwx',
],

Updated permissions

• group:httpadmin permission is removed
• user:apache permission is added
• group:webadmin permission is updated

# file /var/www/site1
user::rwx
group::r-x
other::r-x
mask::rwx
group:webadmin:r--
user:apache:rwx

Using action => unset

The unset option for the action parameter will specify the set of ACLs guaranteed by Puppet to NOT be applied to the path. ACLs applied to the path which match those specified in the permission property will be removed. ACLs applied to the path which do not match those specified in the permission property will remain unchanged.

Initial permissions

# file /var/www/site1
user::rwx
group::r-x
other::r-x
mask::rwx
group:webadmin:r-x
group:httpadmin:rwx

Specified acls

permission  => [
  'user::rwx',
  'group::r-x',
  'other::r-x',
  'mask::rwx',
  'group:webadmin:r--',
  'user:apache:rwx',
],

Updated permissions

# file /var/www/site1
user::rwx
group::r-x
other::r-x
mask::rwx
group:httpadmin:rwx

Using action => purge

The purge option for the action parameter will cause Puppet to remove any file ACLs applied to the path.

NOTE: Although the permission property is unused for this action, it needs to have a valid ACL value for the action to work. This is a known issue.

Initial permissions

# file /var/www/site1
user::rwx
group::r-x
other::r-x
mask::rwx
group:webadmin:r-x
group:httpadmin:rwx

Specified acls

See note above.

permission  => [
  'user::rwx',
  'group::r-x',
  'other::r-x',
  'mask::rwx',
  'group:webadmin:r--',
  'user:apache:rwx',
],

Updated permissions

• All file ACLs are removed.

# file /var/www/site1
user::rwx
group::r-x
other::r-x

Using ignore_missing

The ignore_missing parameter allows to set the behavior in case the specified path does not exist. It can take these values:

• false (default): If the path is missing, an Error is raised.
• notify: If the path is missing, no action is taken, but a notice is shown in the agent output.
• quiet: If the path is missing, the ACL is silently ignored.

Limitations

Conflicts with "file" resource type:

If the path being modified is managed via the File resource type, the path's mode bits must match the value specified in the permission property of the ACL.

Mask check

The ACL setter doesn't recalculate the rights mask based on the user/group ACLs specified, so it is possible to specify ACLs on a file for which a more restrictive set of rights is enforced, known as "effective rights". For example, with these permission parameters on a file test:

permission  => [
  'user::rw-',
  'group::---',
  'mask::r--',
  'other::---',
  'user:apache:rwx',
  'group:root:r-x',
  'group:admin:rwx',
],

The output of getfacl test reveals a more restrictive set of effective rights, which might not be what was expected:

# file: test
# owner: root
# group: root
user::rw-
group::---
other::---
mask::r--
user:apache:rwx                 #effective:r--
group:root:r-x                  #effective:r--
group:admin:rwx                 #effective:r--

Transfer Notice

This plugin was originally authored by John 'dobbymoodge' Lamb. The maintainer preferred that Vox Pupuli take ownership of the module for future improvement and maintenance. Existing pull requests and issues were transferred over, please fork and continue to contribute here instead of Camptocamp.

Previously: https://github.com/dobbymoodgep/puppet-posix_acl

Contributions

Contribution is fairly easy:

• Fork the module into your namespace
• Create a new branch
• Commit your bugfix or enhancement
• Write a test for it (maybe start with the test first)
• Create a pull request

Detailed instructions are in the CONTRIBUTING.md file.

Reference

Table of Contents

Classes

• posix_acl::requirements: install the acl package

Resource types

• posix_acl: Ensures that a set of ACL permissions are applied to a given file or directory. Example: posix_acl { '/var/www/html': action

Classes

posix_acl::requirements

install the acl package

Resource types

posix_acl

Ensures that a set of ACL permissions are applied to a given file or directory.

Example:

 posix_acl { '/var/www/html':
   action      => exact,
   permission  => [
     'user::rwx',
     'group::r-x',
     'mask::rwx',
     'other::r--',
     'default:user::rwx',
     'default:user:www-data:r-x',
     'default:group::r-x',
     'default:mask::rwx',
     'default:other::r--',
   ],
   provider    => posixacl,
   recursive   => true,
 }

In this example, Puppet will ensure that the user and group permissions are set recursively on /var/www/html as well as add default permissions that will apply to new directories and files created under /var/www/html

Setting an ACL can change a file's mode bits, so if the file is managed by a File resource, that resource needs to set the mode bits according to what the calculated mode bits will be, for example, the File resource for the ACL above should be:

 file { '/var/www/html':
        mode => 754,
      }

Properties

The following properties are available in the posix_acl type.

permission

ACL permission(s).

Parameters

The following parameters are available in the posix_acl type.

• action
• ignore_missing
• path
• provider
• recursemode
• recursive

action

Valid values: set, unset, exact, purge

What do we do with this list of ACLs? Options are set, unset, exact, and purge

Default value: set

ignore_missing

Valid values: false, quiet, notify

What to do if files are missing: false: fail run, quiet: quietly do nothing, notify: do not try to to set ACL, but add notice to run

Default value: false

path

namevar

The file or directory to which the ACL applies.

provider

The specific backend to use for this posix_acl resource. You will seldom need to specify this --- Puppet will usually discover the appropriate provider for your platform.

recursemode

Valid values: lazy, deep

Should Puppet apply the ACL recursively with the -R option or apply it to individual files?

lazy means -R option deep means apply to every file

Default value: lazy

recursive

Valid values: true, false

Apply ACLs recursively.

Default value: false

Changelog

All notable changes to this project will be documented in this file. Each new release typically also includes the latest modulesync defaults. These should not affect the functionality of the module.

v3.1.0 (2024-03-14)

Full Changelog

Implemented enhancements:

• Add puppet-strings documentation #129 (bastelfreak)
• README.md: Add badges /transfer notice/contributing notes #128 (bastelfreak)
• Add Ubuntu 20.04/22.04 & Debian 12 #127 (tuxmea)

v3.0.0 (2023-06-26)

Full Changelog

Breaking changes:

• Drop Puppet 6 support #117 (bastelfreak)

Implemented enhancements:

• Add EL9/Rocky/Alma support #121 (bastelfreak)
• Add puppet 8 support #120 (bastelfreak)

v2.0.0 (2022-01-26)

Full Changelog

Breaking changes:

• Drop EoL Debian 9 support #100 (bastelfreak)
• modulesync 5.1.0 / Drop EoL Puppet 5 support #97 (bastelfreak)

Implemented enhancements:

• Add support for Debian 11, RedHat 8 (and derivatives) #95 (smortex)
• Implement handling of missing files #93 (raemer)
• Mark compatible with Puppet 7 #92 (Thelvaen)
• Changed to osfamily to make it work on oracle linux systems #89 (housemasterkrause)

Fixed bugs:

• dont set ACLs if there are no ACLs to change #108 (bastelfreak)
• Properly handle frozen strings #107 (ekohl)

Closed issues:

• FrozenStringLiteral breaks puppet module #104
• Oracle Linux: Warning about multiple default providers #88

Merged pull requests:

• Add acceptance test and documentation for file autorequire #113 (bastelfreak)
• Add test to verify purging ACLs works #111 (bastelfreak)
• Fix typo in documentation #105 (bastelfreak)
• Manage spec_helper_acceptance via modulesync / Enable basic acceptance test #102 (bastelfreak)
• Enable puppet lint for tests/docs #101 (bastelfreak)
• Remove old unsupported Beaker nodesets #90 (ekohl)

v1.1.0 (2021-06-07)

Full Changelog

Implemented enhancements:

• make posix_acl run more efficiently #85 (oniGino)

v1.0.1 (2020-01-30)

Full Changelog

Fixed bugs:

• fix comparing permissions when they have a mix of upper- and lower-ca… #74 (unki)

v1.0.0 (2019-10-29)

Full Changelog

Breaking changes:

• modulesync 2.7.0 and drop puppet 4 #59 (bastelfreak)

Implemented enhancements:

• [RFE] Extend File type to eliminate need for redundant code #16
• Directory +x / Files not +x #9
• Add Gentoo support #66 (paescuj)
• X bit support #61 (jadestorm)

Fixed bugs:

• File is executable when X option is set on directory #64
• Fix for issue #64 #65 (jadestorm)

Closed issues:

• Version release #67
• README not displaying in forge #55
• Solaris support #32

Merged pull requests:

• Expand the operating system support to include Debian 9 and 10 #62 (gfa)
• Change filename to allow rendering on Puppet Forge. #60 (cdchase)

v0.1.1 (2018-10-14)

Full Changelog

Merged pull requests:

• modulesync 2.2.0 and allow puppet 6.x #53 (bastelfreak)

v0.1.0 (2018-07-16)

Full Changelog

Implemented enhancements:

• Move to Vox Pupuli #29

Merged pull requests:

• Remove docker nodesets #47 (bastelfreak)
• drop EOL OSs; fix puppet version range #46 (bastelfreak)
• Rubocop: Fix Style/PredicateName #42 (alexjfisher)
• Rubocop: Fix Style/GuardClause #41 (alexjfisher)
• Rubocop: Fix Lint/UselessAssignment #40 (alexjfisher)
• Rubocop auto fixes #39 (alexjfisher)
• Fix metadata and add LICENSE file #36 (alexjfisher)
• remove ruby 1.9.3 support #35 (dobbymoodge)

0.0.5 (2017-12-12)

Full Changelog

0.0.4 (2017-12-12)

Full Changelog

Fixed bugs:

• module name conflict #26

Closed issues:

• Race condition with non existing file and recursemode => deep #22
• Publish to the forge #21

Merged pull requests:

• Time to deprecate Ruby 1.8.7 support #31 (dobbymoodge)
• Fixes ACL's with spaces #30 (i1tech)
• fix another Ruby error when the file doesn't exist yet #28 (tequeter)
• use inspect instead of join to stringify arrays #27 (tequeter)
• Do not downcase acl group/user names when checking for insync?. #25 (tdevelioglu)
• Check if a path exists before calling getfacl #23 (roidelapluie)

0.0.3 (2016-01-13)

Full Changelog

Closed issues:

• Accept short acls. #4

Merged pull requests:

• Switch from Modulefile to metadata.json #20 (roidelapluie)
• Fix defaults: behaviour #19 (roidelapluie)
• Add autorequire on parent ACL #18 (roidelapluie)
• Fix ruby 1.8.7 quirks #17 (dobbymoodge)
• Better support for 'deep' recursive acls #15 (roidelapluie)
• Adds space around operators in ternary expressions #14 (dobbymoodge)
• Add recursemode parameter to apply ACLs recursively #13 (dobbymoodge)
• Add the Puppetlabs Skeleton for testing #11 (roidelapluie)
• Drop duplicate ACL's. #10 (kevincox)
• Update sync #7 (mwoodson)
• Normalize ACL's. #5 (kevincox)
• Make posixacl the default for the redhat family #3 (nhemingway)
• Add a acl::requirements class #2 (duritong)
• Fix typo and make Modulefile validate by puppet module tool #1 (carlossg)

* This Changelog was automatically generated by github_changelog_generator