|
ACLs: the rights attribute
First off, ACLs. Windows lets you give permissions to multiple users and groups, and the new “rights” attribute gives you control over this powerful feature. It looks like this:
You can add as many (or as few) rights attributes as you like, and Chef will apply them to the file or directory. Here’s the syntax:
The <permissions> parameter specifies the what rights will be granted to the principal. The possible values are :read, :write, :full_control and :deny. These permissions are cumulative: if you specify :write, it includes :read, and :full_control includes both :write and :read. If you specify :deny, the user or group in question will have no rights at all to the object in question.
Editor: insert some nice pretty Windows screenshots showing what these mean with the security dialog box.
For those who know the Windows API. :read corresponds to GENERIC_READ and GENERIC_EXECUTE; :write corresponds to GENERIC_WRITE, GENERIC_READ and GENERIC_EXECUTE, and :full_control corresponds to GENERIC_ALL, allowing a user to change the owner and other metadata about a file.
The <principal> parameter is a string specifying a group name or user name. This can be anything you can type in the logon box for Windows: either "username", "domain\username", or "username@fully_qualified_domain". You don’t need to tell Chef whether it’s a user or group; we’ll figure it out when we look it up. Editor: support for SIDs might be nice. The ability to specify well-known SIDs like Everyone in a language-independent way would be good, too.
The <options> parameter is a hash with several possible advanced rights options. For example, you can add a right to a directory that only applies to its children like this: "rights :write, "UBERDOMAIN\Sales", :applies_to_self => false". This table shows all the options:
| Key |
Possible Values |
Meaning |
| :applies_to_children |
true |
This right will be inherited by both child directories and files (default) |
| |
false |
This right will not be inherited by any child directories or files. |
| |
:containers_only |
Child directories (but not files) will inherit this right. |
| |
:objects_only |
Child files (but not directories) will inherit this right. (This is recursive.) |
| :applies_to_self |
true |
This right will apply to the directory or file resource (default) |
| |
false |
This right will not apply to the directory or file resource, but may apply to any children. |
| :one_level_deep |
true |
Only the first level of children will inherit this right. |
| |
false |
All children (recursively) will inherit this right. |
Other important things to know about rights:
- Rights are order-independent: it doesn't matter whether you say rights :deny, "Sally" before or after rights :read, "Sally", Sally will be unable to read the document.
- When you specify rights, they are considered a complete description of all explicit rights on a file: all existing explicit rights will be removed and the new ones added. (Inherited rights will remain on the file).
- If you do not specify any rights (or mode) on a file, security will remain untouched: More specifically, we will not clear out the rights on the file if you fail to specify rights and mode. We figure if you wanted us to mess with it, you would have told us something. Editor’s Note: we need give the user a way to specify that all rights should be cleared.
- Changing inheritable rights on a directory with many files can be expensive: Chef will make sure not to modify rights when nothing has changed, but when it does a large directory can take a while. This is due to inheritance (Windows will propagate the new rights to all children recursively). This is a normal part of running on Windows, but if you need to do this often, careful control over inheritance options can help you get rid of some of the cost.
Inheritance: the inherits attribute
By default, any file or directory you create inherits rights from its parent directory. Normally this is exactly what you want; but sometimes you want to carve a little space off from the rest of the world where you control every right. You can tell Chef that your file or directory should not inherit rights from its parent by specifying "inherits false":
You could have used :deny to accomplish the same ends, but unless you deny everyone, something could slip through. It all depends on whether you want that or not.
If you do not specify the inherits attribute, Chef will default it to true for new files, but will leave it unchanged for existing files (so if you go modify the file yourself, it will not get flipped back on the next Chef run).
owner, group and mode
You are advised to use owner and right and avoid group and mode, which are not really Windows concepts. Nonetheless, they are provided for backwards compatibility and mean roughly the same thing as they did before, with the following modifications:
- owner: "owner" now supports any username (including fully qualified "domain\user" and "user@domain"). If you do not specify this, new files will pick up the current user as the owner and existing files will leave their owner unchanged.
- group: This now supports any groupname (including fully qualified "domain\group" and "group@domain"). If you do not specify this, new files will get your default POSIX group (which you likely don’t have), and existing files will have their group unchanged.
- mode: This is provided for backwards compatibility. This mask is now translated into rights. Values up to 0777 are allowed (no sticky bits), and mean the same thing as the Unix counterpart, with 4 = GENERIC_READ, 2 = GENERIC_WRITE and 1 = GENERIC_EXECUTE. You cannot give :full_control with mode (but the owner has full control anyway). mode has no effect when it is not specified. When both mode and rights are specified, the effects are cumulative.
|
|
