pyacl/README.md

pyacl

Overview

This is a high level abstraction over the great pylibacl library. It removes the need for low level understanding of POSIX.1e by providing an interface similar to what one is used to by common ACL handling tools such as getfacl(1) and setfacl(1). Handling of ACLs in pyacl happens through a map resembling what one would find as a result of calling getfacl(1).

Example

Reading the ACL of a path

The following shows a file at /tmp/testacl1 on which an ACL granting the user georg2 read permissions was applied.

Result from getfacl(1):

$ getfacl -c /tmp/testacl1
getfacl: Removing leading '/' from absolute path names
user::---
user:georg2:r--
group::r--
mask::r--
other::---

Result from pyacl:

>>> from pyacl import acl
>>> acl.parse_acl_from_path('/tmp/testacl1')
{'user': {'georg2': {'read': True, 'write': False, 'execute': False}},
 'group': {None: {'read': True, 'write': False, 'execute': False}},
 'mask': {None: {'read': True, 'write': False, 'execute': False}},
 'other': {None: {'read': False, 'write': False, 'execute': False}}}

Writing an ACL to a path

The following will apply ACL granting the user georg2 read permissions to a file at /tmp/testacl2.

echo hi > /tmp/testacl2

With setfacl(1):

setfacl -m u:georg2:r /tmp/testacl2

With pyacl:

>>> from pyacl import acl
>>> myacl = acl.build_acl(target_name='georg2', target_type='user', read=True, write=False, execute=False)
>>> acl.apply_acl_to_path(myacl, '/tmp/testacl2')

Of course, the build_acl() call could be shortened by omitting default arguments.

Documentation

The functions provided by pyacl are documented through docstrings. Find them in the source code, or by calling help() - example:

>>> from pyacl import acl
>>> help(acl.build_acl)
Help on function build_acl in module pyacl.acl:

build_acl(target_name, target_type, read=False, write=False, execute=False)
    Example usage: build_acl(target_name='georg2', target_type='user', read=True, write=False, execute=True)
    Return: posix1e.ACL

Hacking/Tests

Functionality is tested through pytest. As it requires a certain test user to be present, easiest is to use the purpose-built container image. A wrapper is provided at scripts/test.sh.