3rdparty/modules/posix_acl/README.org

   1 #+TITLE: Acl module for Puppet
   2
   3 * Description
   4 This plugin module provides a way to set POSIX 1.e (and other standards) file ACLs via Puppet.
   5
   6 * Usage:
   7   - the =posix_acl= resource =title= is used as the path specifier.
   8   - ACLs are specified in the =permission= property as an array of strings in the same format as is used for =setfacl=.
   9   - the =action= parameter can be one of =set=, =exact=, =unset= or =purge=. These are described in detail below.
  10   - the =provider= parameter allows a choice of filesystem ACL provider. Currently only POSIX 1.e is implemented.
  11   - the =recursive= parameter allows you to apply the ACLs to all files under the specified path.
  12
  13     : posix_acl { "/var/log/httpd":
  14     :     action     => set,
  15     :     permission => [
  16     :                    "user::rwx",
  17     :                    "group::---",
  18     :                    "mask::r-x",
  19     :                    "other::---",
  20     :                    "group:logview:r-x",
  21     :                    "default:user::rwx",
  22     :                    "default:group::---",
  23     :                    "default:mask::rwx",
  24     :                    "default:other::---",
  25     :                    "default:group:logview:r-x",
  26     :                    ],
  27     :     provider   => posixacl,
  28     :     require    => [
  29     :                    Group["logview"],
  30     :                    Package["httpd"],
  31     :                    Mount["/var"],
  32     :                    ],
  33     :     recursive  => false,
  34     : }
  35
  36 ** Using action => set:
  37 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.
  38 *** Initial permissions:
  39     : # file /var/www/site1
  40     : user::rwx
  41     : group::r-x
  42     : other::r-x
  43     : mask::rwx
  44     : group:webadmin:r-x
  45     : group:httpadmin:rwx
  46 *** Specified acls:
  47     : permission  => [
  48     :   'user::rwx',
  49     :   'group::r-x',
  50     :   'other::r-x',
  51     :   'mask::rwx',
  52     :   'group:webadmin:rwx',
  53     :   'user:apache:rwx',
  54     : ],
  55 *** Updated permissions:
  56     : # file /var/www/site1
  57     : user::rwx
  58     : group::r-x
  59     : other::r-x
  60     : mask::rwx
  61     : user:apache:rwx
  62     : group:webadmin:rwx
  63     : group:httpadmin:rwx
  64 ** Using action => exact:
  65 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.
  66 *** Initial permissions:
  67     : # file /var/www/site1
  68     : user::rwx
  69     : group::r-x
  70     : other::r-x
  71     : mask::rwx
  72     : group:webadmin:r-x
  73     : group:httpadmin:rwx
  74 *** Specified acls:
  75     : permission  => [
  76     :   'user::rwx',
  77     :   'group::r-x',
  78     :   'other::r-x',
  79     :   'mask::rwx',
  80     :   'group:webadmin:r--',
  81     :   'user:apache:rwx',
  82     : ],
  83 *** Updated permissions:
  84     - group:httpadmin permission is removed
  85     - user:apache permission is added
  86     - group:webadmin permission is updated
  87     : # file /var/www/site1
  88     : user::rwx
  89     : group::r-x
  90     : other::r-x
  91     : mask::rwx
  92     : group:webadmin:r--
  93     : user:apache:rwx
  94 ** Using action => unset:
  95 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.
  96 *** Initial permissions:
  97     : # file /var/www/site1
  98     : user::rwx
  99     : group::r-x
 100     : other::r-x
 101     : mask::rwx
 102     : group:webadmin:r-x
 103     : group:httpadmin:rwx
 104 *** Specified acls:
 105     : permission  => [
 106     :   'user::rwx',
 107     :   'group::r-x',
 108     :   'other::r-x',
 109     :   'mask::rwx',
 110     :   'group:webadmin:r--',
 111     :   'user:apache:rwx',
 112     : ],
 113 *** Updated permissions:
 114     : # file /var/www/site1
 115     : user::rwx
 116     : group::r-x
 117     : other::r-x
 118     : mask::rwx
 119     : group:httpadmin:rwx
 120 ** Using action => purge:
 121 The =purge= option for the =action= parameter will cause Puppet to remove any file ACLs applied to the path.
 122
 123 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.
 124 *** Initial permissions:
 125     : # file /var/www/site1
 126     : user::rwx
 127     : group::r-x
 128     : other::r-x
 129     : mask::rwx
 130     : group:webadmin:r-x
 131     : group:httpadmin:rwx
 132 *** Specified acls:
 133 See above
 134     : permission  => [
 135     :   'user::rwx',
 136     :   'group::r-x',
 137     :   'other::r-x',
 138     :   'mask::rwx',
 139     :   'group:webadmin:r--',
 140     :   'user:apache:rwx',
 141     : ],
 142 *** Updated permissions:
 143     - All file ACLs are removed
 144     : # file /var/www/site1
 145     : user::rwx
 146     : group::r-x
 147     : other::r-x
 148
 149 * Notes:
 150 ** Conflicts with "file" resource type:
 151 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
 152 ** Mask check:
 153 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=:
 154     : permission  => [
 155     :   'user::rw-',
 156     :   'group::---',
 157     :   'mask::r--',
 158     :   'other::---',
 159     :   'user:apache:rwx',
 160     :   'group:root:r-x',
 161     :   'group:admin:rwx',
 162     : ],
 163
 164 The output of =getfacl test= reveals a more restrictive set of effective rights, which might not be what was expected:
 165     : # file: test
 166     : # owner: root
 167     : # group: root
 168     : user::rw-
 169     : group::---
 170     : other::---
 171     : mask::r--
 172     : user:apache:rwx                 #effective:r--
 173     : group:root:r-x                  #effective:r--
 174     : group:admin:rwx                 #effective:r--