Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/puppetlabs/puppetlabs-acl

ACL (Access Control List) module
https://github.com/puppetlabs/puppetlabs-acl

hacktoberfest module supported

Last synced: 8 months ago
JSON representation

ACL (Access Control List) module

Awesome Lists containing this project

README 

          
# acl



#### Table of Contents



1. [Module Description - What does the module do?](#module-description)

1. [Setup - The basics of getting started with acl](#setup)

    * [Beginning with acl - Installation](#beginning-with-acl)

1. [Usage - The custom type available for configuration](#usage)

    * [Manage a basic ACL with all parameters expressed](#manage-a-basic-acl-with-all-parameters-expressed)

    * [Manage multiple permissions at once](#manage-multiple-permissions-at-once)

    * [Same target, multiple resources](#same-target-multiple-resources)

    * [Identify users and groups with SID or FQDN](#identify-users-and-groups-with-sid-or-fqdn)

    * [Use multiple resources to manage the same target](#use-multiple-resources-to-manage-the-same-target)

    * [Protect a target from inherited permissions](#protect-a-target-from-inherited-permissions)

    * [Purge unmanaged explicit permissions](#purge-unmanaged-explicit-permissions)

    * [Protect a target and purge all unmanaged permissions](#protect-a-target-and-purge-all-unmanaged-permissions)

    * [Set ACE mask_specific rights](#set-ace-mask_specific-rights)

    * [Explicitly deny permissions](#explicitly-deny-permissions)

    * [Set ACE inheritance](#set-ace-inheritance)

    * [Set ACE propagation](#set-ace-propagation)

    * [Remove ACE permissions](#remove-ace-permissions)

    * [Use same identity, multiple ACEs](#use-same-identity-multiple-aces)

1. [Reference - An under-the-hood peek at what the module is doing and how](#reference)

1. [Limitations - Known issues in acl](#limitations)

1. [License](#license)

1. [Development - Guide for contributing to the module](#development)



## Module Description



The acl module lets you use Puppet to manage Access Control Lists (ACLs) on Windows.



Windows uses Access Control Lists (ACLs) to store permissions information. An ACL is typically made up of a series of Access Control Entries (ACEs), representing individual permissions. The acl module adds a type and provider to let you manage all that information through Puppet.



## Setup



Install this module with the following command:



~~~puppet

$ puppet module install [--modulepath ] puppetlabs/acl

~~~



The above command also includes the optional argument to specify your Puppet server's `modulepath` as the location to install the module.



### Beginning with acl



For a basic implementation of the acl module, provide a target ACL and at least one permission:



~~~puppet

acl { 'c:/tempperms':

  permissions => [

   { identity => 'Administrator', rights => ['full'] },

   { identity => 'Users', rights => ['read','execute'] }

 ],

}

~~~



## Usage



A typical ACL is made up of access control entries (ACEs), which represent individual permissions. Each ACE comprises a defined trustee (an identity, representing a user, group, or system process), a set of rights, an inheritance and propagation strategy, and an allowed/denied status.



Windows processes ACEs in order of appearance within the ACL. It expects them to be pre-sorted by allowed/denied status in the following order:

 1. 'explicit deny'

 2. 'explicit allow'

 3. 'inherited deny'

 4. 'inherited allow'



The `acl` type does not enforce the above order, and applies the ACEs based on order of appearance in your manifest. If that differs from the ordering above, node users who view or update the ACL through the Windows Security graphical interface receive a warning message: "The permissions on [filename] are incorrectly ordered, which may cause some entries to be ineffective."



**Note:** You cannot specify inherited ACEs in a manifest; you can only specify whether to allow upstream inheritance to flow into the managed ACL.



### Manage a basic ACL with all parameters expressed



The fully expressed ACL in the sample below produces the same settings as the [minimal sample](beginning-with-acl) in the Setup section, without relying on defaults.



~~~puppet

acl { 'c:/tempperms':

  target                     => 'c:/tempperms',

  purge                      => false,

  permissions                => [

   { identity => 'Administrator', rights => ['full'], perm_type=> 'allow', child_types => 'all', affects => 'all' },

   { identity => 'Users', rights => ['read','execute'], perm_type=> 'allow', child_types => 'all', affects => 'all' }

  ],

  owner                      => 'Administrators', #Creator_Owner specific, doesn't manage unless specified

  group                      => 'Users', #Creator_Group specific, doesn't manage unless specified

  inherit_parent_permissions => true,

}

~~~



### Manage multiple permissions at once



The `permissions` parameter is passed as an array, allowing it to accept multiple ACEs in the form of hashes.



~~~puppet

acl { 'c:/tempperms':

  permissions                => [

   { identity => 'Administrators', rights => ['full'] },

   { identity => 'Administrator', rights => ['modify'] },

   { identity => 'Authenticated Users', rights => ['write','read','execute'] },

   { identity => 'Users', rights => ['read','execute'] }

   { identity => 'Everyone', rights => ['read'] }

  ],

  inherit_parent_permissions => false,

}

~~~



 * Each ACE should have a unique combination of `identity`, `perm_type`, `child_types`, and `affects` values. If you create multiple ACEs that differ only in `rights`, the module can't tell them apart and wrongly reports that the resource is out of sync.



**Wrong:**



~~~puppet

acl { 'c:/tempperms':

  permissions => [

    { identity => 'SYSTEM', rights => ['read']},

    { identity => 'SYSTEM', rights => ['write']}

  ],

}

~~~



**Right:**



~~~puppet

acl { 'c:/tempperms':

  permissions => [

    { identity => 'SYSTEM', rights => ['read','write']}

  ],

}

~~~



**Note:** When you run `puppet resource acl some_path`, Puppet might list some permissions with the read-only element `is_inherited => 'true'`. If you use the `resource` output in a manifest, Puppet ignores those permissions. To indicate they should be enforced on the target directly, remove the `is_inherited` property or set `is_inherited => false'`.



For more detail, see the Reference section on [`permissions`](#permissions).



### Identify users and groups with SID or FQDN



You can identify a user or group using a [security identifier](http://support.microsoft.com/kb/243330) (SID) or a fully qualified domain name (FQDN).



~~~puppet

acl { 'c:/tempperms':

  permissions => [

   { identity => 'NT AUTHORITY\SYSTEM', rights => ['modify'] },

   { identity => 'BUILTIN\Users', rights => ['read','execute'] },

   { identity => 'S-1-5-32-544', rights => ['write','read','execute'] }

  ],

}

~~~



#### Use multiple resources to manage the same target



You can manage the same target across multiple ACL resources, as long as each resource has a unique title.



**Warning:** Use this feature with care; it can get confusing quickly. Do not set `purge => 'true'` on any of the resources that apply to the same target. Doing so causes thrashing in reports, as the permissions are added and removed on every catalog application.



~~~puppet

acl { 'c:/tempperms':

  permissions => [

   { identity => 'Administrator', rights => ['full'] }

 ],

}



acl { 'tempperms_Users':

  target      => 'c:/tempperms',

  permissions => [

   { identity => 'Users', rights => ['read','execute'] }

 ],

}

~~~



#### Protect a target from inherited permissions



Removing upstream inheritance is known as "protecting" the target. When an item is protected without `purge => true`, the inherited ACEs are copied into the target as unmanaged ACEs.



~~~puppet

acl { 'c:/tempperms':

  permissions                => [

   { identity => 'Administrators', rights => ['full'] },

   { identity => 'Users', rights => ['full'] }

  ],

  inherit_parent_permissions => false,

}

~~~



#### Purge unmanaged explicit permissions



You cannot purge inherited permissions; you can only purge explicit permissions. To lock down a folder to managed explicit ACEs, set `purge => true`. This only removes other explicit ACEs from the folder that are unmanaged by this resource. All inherited ACEs remain (see next example).



~~~puppet

acl { 'c:/tempperms':

  purge       => true,

  permissions => [

   { identity => 'Administrators', rights => ['full'] },

   { identity => 'Users', rights => ['full'] }

  ],

}

~~~



#### Protect a target and purge all unmanaged permissions



To fully restrict a target's permissions to the ones specified in your manifest, protect it as above and set `purge => 'true'`.



**Warning**: When removing permissions, make sure the user running Puppet always has FULL rights on the target. If Puppet loses its permission to manage a resource, you'll need to restore it manually at the node level.



~~~puppet

acl { 'c:/tempperms':

  purge                           => true,

  permissions                     => [

   { identity => 'Administrators', rights => ['full'] },

   { identity => 'Users', rights => ['full'] }

  ],

  inherit_parent_permissions => false,

}

~~~



#### Set ACE mask_specific rights



If none of the standard `rights` values meets your specific needs, you can specify more granular rights by setting `rights => ['mask_specific']` and supplying a 'mask' element with an integer representing a [permissions mask](http://msdn.microsoft.com/en-us/library/aa394063(v=vs.85).aspx). You can't combine the mask with other values, such as read permissions.



**NOTE:** 'mask_specific' should ONLY be used when other rights are not specific enough. If you specify 'mask_specific' with the equivalent of 'full' rights (2032127), and Puppet finds the property to be 'full', it reports making changes to the resource even though nothing is different.



~~~puppet

acl { 'c:/tempperms':

  purge                      => true,

  permissions                => [

   { identity => 'Administrators', rights => ['full'] }, #full is same as - 2032127 aka 0x1f01ff but you should use 'full'

   { identity => 'SYSTEM', rights => ['modify'] }, #modify is same as 1245631 aka 0x1301bf but you should use 'modify'

   { identity => 'Users', rights => ['mask_specific'], mask => '1180073' }, #RX WA #0x1201a9

   { identity => 'Administrator', rights => ['mask_specific'], mask => '1180032' }  #RA,S,WA,Rc #1180032  #0x120180

  ],

  inherit_parent_permissions => false,

}

~~~



**More about ACE masks:**



 * File/Directory Access Mask Constants: http://msdn.microsoft.com/en-us/library/aa394063(v=vs.85).aspx

 * Generic File Access Rights: http://msdn.microsoft.com/en-us/library/windows/desktop/aa364399(v=vs.85).aspx

 * Access Mask Format: http://msdn.microsoft.com/en-us/library/windows/desktop/aa374896(v=vs.85).aspx



#### Explicitly deny permissions



By default, each ACE grants the described permissions to the target. However, you can reverse that by setting `perm_type => 'deny'`, which explicitly removes the described permissions. List your 'deny' ACEs first, before your 'allow' ACEs.



~~~puppet

acl { 'c:/tempperms':

  permissions => [

   { identity => 'SYSTEM', rights => ['full'], perm_type=> 'deny', affects => 'self_only' },

   { identity => 'Administrators', rights => ['full'] }

  ],

}

~~~



#### Set ACE inheritance



The inheritance structure of ACEs is controlled by [`child_types`](#permissions), which determine how files and sub-folders inherit each ACE.



~~~puppet

acl { 'c:/tempperms':

  purge                      => true,

  permissions                => [

   { identity => 'SYSTEM', rights => ['full'], child_types => 'all' },

   { identity => 'Administrators', rights => ['full'], child_types => 'containers' },

   { identity => 'Administrator', rights => ['full'], child_types => 'objects' },

   { identity => 'Users', rights => ['full'], child_types => 'none' }

  ],

  inherit_parent_permissions => false,

}

~~~



#### Set ACE propagation



ACEs have propagation rules which guide how they apply permissions to containers, objects, children, and grandchildren. Propagation is determined by [`affects`](#permissions), which can take the value of: 'all', 'self_only', 'children_only', 'direct_children_only', and 'self_and_direct_children_only'. Microsoft has a [good matrix](http://msdn.microsoft.com/en-us/library/ms229747.aspx) that outlines when and why you might use each of these values.



~~~puppet

acl { 'c:/tempperms':

  purge                      => true,

  permissions                => [

   { identity => 'Administrators', rights => ['modify'], affects => 'all' },

   { identity => 'Administrators', rights => ['full'], affects => 'self_only' },

   { identity => 'Administrator', rights => ['full'], affects => 'direct_children_only' },

   { identity => 'Users', rights => ['full'], affects => 'children_only' },

   { identity => 'Authenticated Users', rights => ['read'], affects => 'self_and_direct_children_only' }

  ],

  inherit_parent_permissions => false,

}

~~~



#### Remove ACE permissions



To remove permissions, set `purge => listed_permissions`. This removes explicit permissions from the ACL based on their `identity`, `perm_type`, `child_types` and `affects` attributes. The example below ensures that 'Administrator' and 'Authenticated Users' are not on the ACL.



~~~puppet

# set permissions

acl { 'c:/tempperms/remove':

  purge                      => true,

  permissions                => [

   { identity => 'Administrators', rights => ['full'] },

   { identity => 'Administrator', rights => ['write'] },

   { identity => 'Users', rights => ['write','execute'] },

   { identity => 'Everyone', rights => ['execute'] },

   { identity => 'Authenticated Users', rights => ['full'] }

  ],

  inherit_parent_permissions => false,

}



# now remove some permissions

acl { 'remove_tempperms/remove':

  target                     => 'c:/tempperms/remove',

  purge                      => 'listed_permissions',

  permissions                => [

   { identity => 'Administrator', rights => ['write'] },

   { identity => 'Authenticated Users', rights => ['full'] }

  ],

  inherit_parent_permissions => false,

  require                    => Acl['c:/tempperms/remove'],

}

~~~



#### Same identity, multiple ACEs



With Windows, you can specify the same `identity` with different inheritance and propagation. Each of the resulting items is managed as a separate ACE.



~~~puppet

acl { 'c:/tempperms':

  purge                      => true,

  permissions                => [

   { identity => 'SYSTEM', rights => ['modify'], child_types => 'none' },

   { identity => 'SYSTEM', rights => ['modify'], child_types => 'containers' },

   { identity => 'SYSTEM', rights => ['modify'], child_types => 'objects' },

   { identity => 'SYSTEM', rights => ['full'], affects => 'self_only' },

   { identity => 'SYSTEM', rights => ['read','execute'], affects => 'direct_children_only' },

   { identity => 'SYSTEM', rights => ['read','execute'], child_types=>'containers', affects => 'direct_children_only' },

   { identity => 'SYSTEM', rights => ['read','execute'], child_types=>'objects', affects => 'direct_children_only' },

   { identity => 'SYSTEM', rights => ['full'], affects => 'children_only' },

   { identity => 'SYSTEM', rights => ['full'], child_types=>'containers', affects => 'children_only' },

   { identity => 'SYSTEM', rights => ['full'], child_types=>'objects', affects => 'children_only' },

   { identity => 'SYSTEM', rights => ['read'], affects => 'self_and_direct_children_only' },

   { identity => 'SYSTEM', rights => ['read'], child_types=>'containers', affects => 'self_and_direct_children_only' },

   { identity => 'SYSTEM', rights => ['read'], child_types=>'objects', affects => 'self_and_direct_children_only' }

  ],

  inherit_parent_permissions => false,

}

~~~



## Reference



### Defined type: acl



The main type of the module, responsible for all its functionality.



#### Parameters



All of the below parameters are optional, unless otherwise noted.



##### `group`



Specifies whose permissions to manage. This identity is also known as a trustee or principal. If the identity doesn't exist on a node, Puppet creates it. Valid options: a string containing a valid identity (see below). Default: if left undefined, Puppet leaves the group as currently configured.



Valid identity formats:



 * User: e.g., 'Bob' or 'TheNet\Bob'

 * Group: e.g., 'Administrators' or 'BUILTIN\Administrators'

 * SID (Security ID): e.g., 'S-1-5-18'



**NOTE**: On Windows the CREATOR GROUP inherited ACE must be set for the creator's primary group for it to be set as an ACE automatically. Group is not always widely used. By default, the group also needs to be specifically set as an explicitly managed ACE. See [Microsoft's page](http://support.microsoft.com/kb/126629) for instructions on enabling CREATOR GROUP.



##### `inherit_parent_permissions`



Specifies whether to inherit permissions from parent ACLs. Valid options: 'true' and 'false'. Default: 'true'.



##### `name`



Provides a name for the ACL resource; also becomes the target, if `target` is not set. Valid options: a string. Default: the title of your declared resource.



##### `owner`



The identity that owns the ACL. If the identity doesn't exist on a node, Puppet creates it. This identity is also known as a trustee or principal. Valid options: a string containing a valid identity (see below). Default: if left undefined, Puppet leaves the owner as currently configured.



Valid identity formats:



 * User: for example, 'Bob' or 'TheNet\Bob'

 * Group: for example, 'Administrators' or 'BUILTIN\Administrators'

 * SID (Security ID): for example, 'S-1-5-18'



##### `permissions`



*Required.* Specifies one or more Access Control Entries (ACEs). Valid options: an ordered array of hashes, each containing at least the `identity` and `rights` elements, and any number of additional elements from the list below.



**Elements in `permissions`**



 * `affects`: *Optional.* Determines how the downstream inheritance is propagated. Valid options: 'all', 'self_only', 'children_only', 'self_and_direct_children_only', and 'direct_children_only'. Default: 'all'.



 * `child_types`: *Optional.* Determines how an ACE is inherited downstream from the target. Valid options: 'all', 'objects', 'containers' and 'none'. Default: 'all'.



 * `identity`: *Required.* Determines whose permissions to manage. If the specified identity doesn't exist on a node, Puppet creates it. Valid options: a user (e.g., 'Bob' or 'TheNet\Bob'), group (e.g., 'Administrators' or 'BUILTIN\Administrators'), or security ID (for example, 'S-1-5-18').



 * `mask`: *Required if `rights => 'mask_specific'` is set.* Indicates rights granted or denied to the trustee. If the `rights` element isn't set to 'mask_specific', the `mask` element has no effect. Valid options: an integer (set as a string, for example '511'), representing a [permissions mask](http://msdn.microsoft.com/en-us/library/aa394063(v=vs.85).aspx).



  If you want more granular detail about `mask` values, we've provided an [ACL Mask Rights Addition spreadsheet](https://github.com/puppetlabs/puppetlabs-acl/blob/main/tools/ACL_Access_Rights_Mask_Addition.xlsx) in the acl module's `tools` directory.



 * `perm_type`: *Optional.* Specifies whether the target should or should *not* have the described permissions. Valid options: 'allow' and 'deny'. Default: 'allow'.



 * `rights`: *Required.*: Valid options: an array containing one or more of the following values: 'full', 'modify', 'mask_specific', 'write', 'read', and 'execute'.



**NOTE:** The `type` element is deprecated and has been replaced with `perm_type`, because the word `type` will be a reserved keyword in Puppet 4.



    * 'read', 'write', and 'execute' can be used together in any combination.

    * 'modify' includes READ, WRITE, EXECUTE, and DELETE all in one.

    * 'full' indicates all rights.

    * 'full', 'modify', and 'mask_specific' values are mutually exclusive. If you use any of them, it must be the *only* `rights` value in the hash.

    * If you specify 'full' or 'modify' along with other rights, e.g., `rights => ['full','read']`, the `acl` type issues a warning and removes the other items.

    * If you specify 'mask_specific', you must also specify the `mask` element in the `permissions` hash with an integer representing a [permissions mask](http://msdn.microsoft.com/en-us/library/aa394063(v=vs.85).aspx).



##### `purge`



Specifies whether to remove any explicit permissions not specified in the `permissions` property. Valid options: 'true', 'false', and 'listed_permissions'. Default: 'false'.



To ensure that a specific set of permissions are absent from the ACL, set `purge => 'listed_permissions'`.



**Note:** This parameter only affects explicit permissions. To remove inherited permissions, use `inherit_parent_permissions => 'false'`.



**Warning:** When removing permissions, make sure the user running Puppet always has FULL rights on the target. If Puppet loses its permission to manage a resource, you'll need to restore it manually at the node level.



##### `target`



*Optional.* The location of the ACL resource. Defaults to `name` value. Valid options: a string containing an absolute path. Default: title of your declared resource.



## Limitations



 * The Windows Provider does not follow Symlinks. Please explicitly manage the permissions of the target.



 * The 8.3 short filename format used in some versions of Windows is not supported.



 * We don't recommend using the acl module with Cygwin, because it can yield inconsistent results --- especially when using Cygwin SSHD with public key authentication. For example, the 'Administrator' identity might work normally on Windows 2012, but on Windows 2008 it might be translated to 'cyg_server' (or vice-versa).



 * Unicode encoding isn't supported in the `identity`, `group`, or `owner` parameters.



 * When using SIDs for identities, autorequire tries to match to users with fully qualified names (e.g., User[BUILTIN\Administrators]) in addition to SIDs (User[S-1-5-32-544]). However, it can't match against 'User[Administrators]', because that could cause issues if domain accounts and local accounts share the same name e.g., 'Domain\Bob' and 'LOCAL\Bob'.



 * When referring to accounts in the `APPLICATION PACKAGE AUTHORITY`, with Puppet versions older than **6.22.0** or **7.5.0**, use either their SID values or their unqualified names. The Windows API has well documented bugs preventing the fully qualifed account names from being used.



    * `S-1-15-2-1` or `ALL APPLICATION PACKAGES`, but *not* `APPLICATION PACKAGE AUTHORITY\ALL APPLICATION PACKAGES`. This account may only be referenced on Windows 2012R2 (kernel 6.3) or newer.

    * `S-1-15-2-2` or `ALL RESTRICTED APPLICATION PACKAGES`, but *not* `APPLICATION PACKAGE AUTHORITY\ALL RESTRICTED APPLICATION PACKAGES`. This account may only be referenced on Windows 2016 (kernel 10.0) or newer.



Please log tickets and issues at our [Module Issue Tracker](https://tickets.puppet.com/browse/MODULES).



## License



This codebase is licensed under the Apache2.0 licensing, however due to the nature of the codebase the open source dependencies may also use a combination of [AGPL](https://www.gnu.org/licenses/agpl-3.0.en.html), [BSD-2](https://opensource.org/license/bsd-2-claus), [BSD-3](https://opensource.org/license/bsd-3-claus), [GPL2.0](https://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html), [LGPL](https://opensource.org/license/lgpl-3-0/), [MIT](https://opensource.org/license/mit/) and [MPL](https://opensource.org/license/mpl-2-0/) Licensing.



## Development



We are experimenting with a new tool for running acceptance tests. It's name is [puppet_litmus](https://github.com/puppetlabs/puppet_litmus) this replaces beaker as the test runner. To run the acceptance tests follow the instructions [here](https://github.com/puppetlabs/puppet_litmus/wiki/Tutorial:-use-Litmus-to-execute-acceptance-tests-with-a-sample-module-(MoTD)#install-the-necessary-gems-for-the-module).



Puppet modules on the Puppet Forge are open projects, and community contributions are essential for keeping them great. We can’t access the huge number of platforms and myriad of hardware, software, and deployment configurations that Puppet is intended to serve.



We want to keep it as easy as possible to contribute changes so that our modules work in your environment. There are a few guidelines that we need contributors to follow so that we can have a chance of keeping on top of things.



For more information, see our [module contribution guide.](https://puppet.com/docs/puppet/latest/contributing.html)



### Contributors



To see who's already involved, see the [list of contributors.](https://github.com/puppetlabs/puppetlabs-acl/graphs/contributors)