POSIX.1e ACLs manipulation

This module provides support for manipulating POSIX.1e ACLS

Depending on the operating system support for POSIX.1e, the ACL type will have more or less capabilities:

  • level 1, only basic support, you can create ACLs from files and text descriptions; once created, the type is immutable

  • level 2, complete support, you can alter the ACL once it is created

Also, in level 2, more types are available, corresponding to acl_entry_t (the Entry type), acl_permset_t (the Permset type).

The existence of level 2 support and other extensions can be checked by the constants:

Example:

>>> import posix1e
>>> acl1 = posix1e.ACL(file="file.txt") 
>>> print acl1
user::rw-
group::rw-
other::r--
>>>
>>> b = posix1e.ACL(text="u::rx,g::-,o::-")
>>> print b
user::r-x
group::---
other::---
>>>
>>> b.applyto("file.txt")
>>> print posix1e.ACL(file="file.txt")
user::r-x
group::---
other::---
>>>
posix1e.ACL_USER

Denotes a specific user entry in an ACL.

posix1e.ACL_USER_OBJ

Denotes the user owner entry in an ACL.

posix1e.ACL_GROUP

Denotes the a group entry in an ACL.

posix1e.ACL_GROUP_OBJ

Denotes the group owner entry in an ACL.

posix1e.ACL_OTHER

Denotes the ‘others’ entry in an ACL.

posix1e.ACL_MASK

Denotes the mask entry in an ACL, representing the maximum access granted other users, the owner group and other groups.

posix1e.ACL_UNDEFINED_TAG

An undefined tag in an ACL.

posix1e.ACL_READ

Read permission in a permission set.

posix1e.ACL_WRITE

Write permission in a permission set.

posix1e.ACL_EXECUTE

Execute permission in a permission set.

posix1e.HAS_ACL_ENTRY

denotes support for level 2 and the Entry/Permset classes

posix1e.HAS_ACL_FROM_MODE

denotes support for building an ACL from an octal mode

posix1e.HAS_ACL_CHECK

denotes support for extended checks of an ACL’s validity

posix1e.HAS_EXTENDED_CHECK

denotes support for checking whether an ACL is basic or extended

posix1e.HAS_EQUIV_MODE

denotes support for the equiv_mode function

posix1e.HAS_COPY_EXT

denotes support for __getstate__()/__setstate__() on an ACL

class posix1e.ACL

Type which represents a POSIX ACL

Note

only one keyword parameter should be provided

Parameters:

  • file (string/bytes/path-like) – creates an ACL representing the access ACL of the specified file or directory.

  • filedef (string/bytes/path-like) – creates an ACL representing the default ACL of the given directory.

  • fd (int/iostream) – creates an ACL representing the access ACL of the given file descriptor.

  • text (string) – creates an ACL from a textual description; note the ACL must be valid, which means including a mask for extended ACLs, similar to setfacl --no-mask

  • acl (ACL) – creates a copy of an existing ACL instance.

  • mode (int) – creates an ACL from a numeric mode (e.g. mode=0644); this is valid only when the C library provides the acl_from_mode call, and note that no validation is done on the given value.

  • data (bytes) – creates an ACL from a serialised form, as provided by calling __getstate__() on an existing ACL

If no parameters are passed, an empty ACL will be created; this makes sense only when your OS supports ACL modification (i.e. it implements full POSIX.1e support), otherwise the ACL won’t be useful.

append([entry])

Append a new Entry to the ACL and return it.

This is a convenience function to create a new Entry and append it to the ACL. If a parameter of type Entry instance is given, the entry will be a copy of that one (as if copied with Entry.copy()), otherwise, the new entry will be empty.

Return type:

Entry

Returns:

the newly created entry

applyto(item[, flag=ACL_TYPE_ACCESS])

Apply the ACL to a file or filehandle.

Parameters:

  • item – either a filename or a file-like object or an integer; this represents the filesystem object on which to act

  • flag – optional flag representing the type of ACL to set, either ACL_TYPE_ACCESS (default) or ACL_TYPE_DEFAULT

calc_mask()

Compute the file group class mask.

The calc_mask() method calculates and sets the permissions associated with the ACL_MASK Entry of the ACL. The value of the new permissions is the union of the permissions granted by all entries of tag type ACL_GROUP, ACL_GROUP_OBJ, or ACL_USER. If the ACL already contains an ACL_MASK entry, its permissions are overwritten; if it does not contain an ACL_MASK Entry, one is added.

The order of existing entries in the ACL is undefined after this function.

check()

Check the ACL validity.

This is a non-portable, Linux specific extension that allow more information to be retrieved in case an ACL is not valid than via the valid() method.

This method will return either False (the ACL is valid), or a tuple with two elements. The first element is one of the following constants:

  • ACL_MULTI_ERROR: The ACL contains multiple entries that have a tag type that may occur at most once

  • ACL_DUPLICATE_ERROR: The ACL contains multiple ACL_USER or ACL_GROUP entries with the same ID

  • ACL_MISS_ERROR: A required entry is missing

  • ACL_ENTRY_ERROR: The ACL contains an invalid entry tag type

The second element of the tuple is the index of the entry that is invalid (in the same order as by iterating over the ACL entry)

delete_entry(entry)

Deletes an entry from the ACL.

Note

Only available with level 2.

Parameters:

entry – the Entry object which should be deleted; note that after this function is called, that object is unusable any longer and should be deleted

equiv_mode()

Return the octal mode the ACL is equivalent to.

This is a non-portable, Linux specific extension that checks if the ACL is a basic ACL and returns the corresponding mode.

Return type:

integer

Raises:

IOError – An IOerror exception will be raised if the ACL is an extended ACL.

to_any_text([prefix='', separator='n', options=0])

Convert the ACL to a custom text format.

This method encapsulates the acl_to_any_text() function. It allows a customized text format to be generated for the ACL. See acl_to_any_text(3) for more details.

Parameters:

  • prefix (string) – if given, this string will be pre-pended to all lines

  • separator (string) – a single character (defaults to ‘n’); this will be used to separate the entries in the ACL

  • options –

    a bitwise combination of:

    • TEXT_ABBREVIATE: use ‘u’ instead of ‘user’, ‘g’ instead of ‘group’, etc.

    • TEXT_NUMERIC_IDS: User and group IDs are included as decimal numbers instead of names

    • TEXT_SOME_EFFECTIVE: Include comments denoting the effective permissions when some are masked

    • TEXT_ALL_EFFECTIVE: Include comments after all ACL entries affected by an ACL_MASK entry

    • TEXT_SMART_INDENT: Used in combination with the _EFFECTIVE options, this will ensure that comments are aligned to the fourth tab position (assuming one tab equals eight spaces)

Return type:

string

valid()

Test the ACL for validity.

This method tests the ACL to see if it is a valid ACL in terms of the file-system. More precisely, it checks that:

The ACL contains exactly one entry with each of the ACL_USER_OBJ, ACL_GROUP_OBJ, and ACL_OTHER tag types. Entries with ACL_USER and ACL_GROUP tag types may appear zero or more times in an ACL. An ACL that contains entries of ACL_USER or ACL_GROUP tag types must contain exactly one entry of the ACL_MASK tag type. If an ACL contains no entries of ACL_USER or ACL_GROUP tag types, the ACL_MASK entry is optional.

All user ID qualifiers must be unique among all entries of the ACL_USER tag type, and all group IDs must be unique among all entries of ACL_GROUP tag type.

The method will return 1 for a valid ACL and 0 for an invalid one. This has been chosen because the specification for acl_valid(3) in the POSIX.1e standard documents only one possible value for errno in case of an invalid ACL, so we can’t differentiate between classes of errors. Other suggestions are welcome.

Returns:

0 or 1

Return type:

integer

class posix1e.Entry

Type which represents an entry in an ACL.

The type exists only if the OS has full support for POSIX.1e Can be created either by:

>>> e = posix1e.Entry(myACL) # this creates a new entry in the ACL
>>> e = myACL.append() # another way for doing the same thing

or by:

>>> for entry in myACL:
...     print entry

Note that the Entry keeps a reference to its ACL, so even if you delete the ACL, it won’t be cleaned up and will continue to exist until its Entry(ies) will be deleted.

copy(src)

Copies an ACL entry.

This method sets all the parameters to those of another entry (either of the same ACL or belonging to another ACL).

Parameters:

src (Entry) – instance of type Entry

parent

The parent ACL of this entry

permset

The permission set of this ACL entry

qualifier

The qualifier of the current entry

If the tag type is ACL_USER, this should be a user id. If the tag type if ACL_GROUP, this should be a group id. Else it doesn’t matter.

tag_type

The tag type of the current entry

This is one of:
class posix1e.Permset

Type which represents the permission set in an ACL entry

The type exists only if the OS has full support for POSIX.1e Can be retrieved either by:

>>> perms = myEntry.permset

or by:

>>> perms = posix1e.Permset(myEntry)

Note that the Permset keeps a reference to its Entry, so even if you delete the entry, it won’t be cleaned up and will continue to exist until its Permset will be deleted.

add(perm)

Add a permission to the permission set.

This function adds the permission contained in the argument perm to the permission set. An attempt to add a permission that is already contained in the permission set is not considered an error.

Parameters:

perm – a permission (ACL_WRITE, ACL_READ, ACL_EXECUTE, …)

Raises:

IOError – in case the argument is not a valid descriptor

clear()

Clears all permissions from the permission set.

delete(perm)

Delete a permission from the permission set.

This function deletes the permission contained in the argument perm from the permission set. An attempt to delete a permission that is not contained in the permission set is not considered an error.

Parameters:

perm – a permission (ACL_WRITE, ACL_READ, ACL_EXECUTE, …)

Raises:

IOError – in case the argument is not a valid descriptor

execute

Execute permission property

This is a convenience method of retrieving and setting the execute permission in the permission set; the same effect can be achieved using the functions add(), test(), delete(), and those can take any permission defined by your platform.

read

Read permission property

This is a convenience method of retrieving and setting the read permission in the permission set; the same effect can be achieved using the functions add(), test(), delete(), and those can take any permission defined by your platform.

test(perm)

Test if a permission exists in the permission set.

The test() function tests if the permission represented by the argument perm exists in the permission set.

Parameters:

perm – a permission (ACL_WRITE, ACL_READ, ACL_EXECUTE, …)

Return type:

Boolean

Raises:

IOError – in case the argument is not a valid descriptor

write

Write permission property

This is a convenience method of retrieving and setting the write permission in the permission set; the same effect can be achieved using the functions add(), test(), delete(), and those can take any permission defined by your platform.

posix1e.delete_default(path)

Delete the default ACL from a directory.

This function deletes the default ACL associated with a directory (the ACL which will be ANDed with the mode parameter to the open, creat functions).

Parameters:

path (string) – the directory whose default ACL should be deleted

posix1e.has_extended(item)

Check if a file or file handle has an extended ACL.

Parameters:

item – either a file name or a file-like object or an integer; it represents the file-system object on which to act