ACLbit - ACL Backup and Inspect Tool Files

ACLbit -- ACL Backup and Inspect Tool
*************************************

**ACLbit** is a command line tool to backup and restore POSIX ACLs on Linux
file systems. The tool uses its backup database to inspect ACLs. 

The inspect part of **ACLbit** focuses on providing clear and concise
output of effective access rights of a particular user.  The main
purpose is to make life of sysadmins easier when finding out current
access rights of a particular user when ACLs are in use, on systems with
tens/hundreds of thousands of inodes, especially. 

The tool is very fast both in backup and inspect phases. Backup is about
30% faster then simple "getfacl /mnt/test >file". We found no tool to
compare to that provides the inspect phase. The times differ for users
with a lot of ACLs and for users with a few. 

**ACLbit** is tool to backup ACLs only. It is not an archiver so it does not
backup the files themselves.


Featrues 
========

- Fast backup & recovery of ACLs
- Fast effective user rights search
- Fast group rights search
- Optimized for huge amounts of files/directories
- Clear and concise output
- Standards compliant
- Free

Limitations:

- Backs up only access ACLs, not default ACLs
- No support for symbolic links


Overview
========

POSIX ACLs are a power feature of most modern file system. They extend
the limitted owner-group-others access rights system with more
fine-grained access control. With ACLs we can set different access
rights on a single file/directory to users Joe and Tom, which is not
possible in the traditional owner-group-others. Use the links below or
Google to find more about Linux (or POSIX) ACLs.

One of the the reasons to use ACLs in enterprise environment can be
Samba. With Samba it is possible to create a Windows domain and/or
Windows shares on a Linux box for free. Since Windows administrators are
used to set complicated access rights, they want the same functionality
when using Samba. Therefore Samba maps Windows ACLs to Linux ACLs.

This is the scenario where our story starts. However, the solution we
developed is general Linux ACL solution not limited to use of Samba.

A responsible system administrator who works with ACLs needs to handle
two important tasks concerning ACLs: *backup* and *inspect*.

The *backup* task can be solved nowadays using either ACL-compliant
archiver or backing up files and ACLs separately. The most known
ACL-compliant archiver seems to be **star** that has outstanding
features and is a tool of choice if you want to go this way.  On the
other hand, if you want to backup ACLs separately, you will probably
choose the standard **getfacl** and **setfacl** programs. The former can
be used for the backup part, as it simply outputs ACLs to standard
output, while the latter can be used for the restore part as it takes
the output of getfacl to set ACLs in file system.

So far, either approach you choose there are mature tools to use to
solve the backup task.

The *inspect* task is far more complicated and I was not able to find
a simple and fast tool that could be any help. So what is the problem?
A system administrator who takes his job seriously needs answers to two
basic questions.

- Who has access rights to a file/directory?
- What access rights are set to Joe?

The first question can be easily answered using getfacl, as for a single
file/directory it outputs understandable text. 

However, getfacl output is no use for anyone asking the second question
on a file system with more then 20 files. The problem is that getfacl is
a simple tool that only lists ACLs for the inspected files or
directories. It does not count effective rights of a user, nor
recognizes that parent directory has the same access rights as its
files/subdirectories.

And here comes the mighty **ACLbit**. Once a file system or its part is
backed up, **ACLbit** can use the backup database to provide the system
administrator with clear and concise answer to the second question. 

System administrator asks the second question.

$ aclbit -U joe

And gets immediate answer.

rwx /usr/local/joes
--- /usr/local/joes/something/restricted
r-x /usr/local/joes/something/restricted/and/allowed/again

Notice that the user rights displayed are correctly computed effective
access rights of user Joe. This means:
- if Joe is owner, it is the owner rights, 
- otherwise if Joe is a named user, it is the respective right, with mask applied
- otherwise if Joe is a member of the owning group or of one of the named groups, it is the logical or of all the groups Joe is member of, with mask applied
- otherwise, it is the access rights of other

Further notice that there is no access rights printed for directory
/usr/local/joes/something. This is due to an important feature of
**ACLbit**: it does not output accesss rights on a file/directory if it is
the same as access rights on its parent.


Download
========

The **ACLbit** project is hosted on SourceForge.net. Download ACLbit release from there.

"ACLbit on SourceForge.net":[http://sourceforge.net/projects/aclbit/]


Install
=======

System Requirements
-------------------
- PHP 5.2 and above

Install
-------

Place the executable in a folder of your choice.

It is goor to put in a path in your $PATH variable.
Good places:

    /usr/bin
    /usr/local/bin

Configure
---------

Optionally, create a configuration file to specify the path to your
database. This step is not necessary.

Create a file with the same name as the executable (aclbit) in one of
the following directories.

>   ../etc (relative to your executable)
>   /etc
>   /usr/local/etc

The directories are search for the configuration file in this order.

Register the path to a database of your choice and tell if you want to
backup ACLs for files or for direcotries only:

; Where is your backup database? 
; Enter absolute path.
database=/var/aclbit.sdb

; Do you want to backup ACLs for files?
; Default is 0, ACLs are backed up for directories only.
files=1


Quickstart
==========

Let's jump straight into **ACLbit** usage. 

All the following samples assume that you have set up a configuration
file with the database option in it. If it is not the case, append the
following option to each aclbit call with the path to your database.


--database /var/aclbit.sdb

**Backup** ACLs of directories rooted in /mnt/test.

$ aclbit --backup /mnt/test

**Inspect** effective rights of user *joe*.

$ aclbit -U joe

**Inspect** ACLs with an entry for group *smbusers*.

$ aclbit -G smbusers

**Inspect** ACLs for /mnt/test/path/to/something.

$ aclbit -F /mnt/test/path/to/something

**Inspect** ACLs for /mnt/test/path/to/something, recursively.

$ aclbit -F /mnt/test/path/to/something --recursive

**Restore** ACLs for /mnt/test/path/to/something.

$ aclbit --restore /mnt/test/path/to/something

**Restore** ACLs for /mnt/test/path/to/something, recursively.

$ aclbit --restore /mnt/test/path/to/something --recursive

**Dump** ACLs backed up for /mnt/test backup root.

$ aclbit --dump /mnt/test

**Print** backup roots in db.

$ aclbit --roots

**Remove** ACLs backed up for backup root /mnt/test from database.

$ aclbit --remove /mnt/test


Usage
=====

All the following samples assume that you have set up a configuration
file with the database option in it. If it is not the case, append the
following option to each aclbit call with the path to your database.

--database /var/aclbit.sdb


Backup
------

The backup operation extracts ACLs from the directory, its
subdirectories, and files, optionally. The extracted ACLs are saved in
an **ACLbit** backup database file.

*Example:* Backup ACLs of directories in /mnt/test.

$ aclbit --backup /mnt/test

*Example:* Backup ACLs of directories and files in /mnt/test.

$ aclbit --backup /mnt/test --files

The directory backed up is called a *backup root*. 

It is possible to have multiple backup roots in one **ACLbit** backup
database. Use --roots option to display all backup roots in database.

*Example:* Backup ACLs of directories in /mnt/test2.

$ aclbit --backup /mnt/test2

The backup roots cannot overlap. This means that the new backup root
cannot be an ancestor or descendant of an existing backup root.

However, it is possilbe to run the backup operation on a backup root
that is already in database. In such a case, the new backup replaces the
old backup.


Inspect effective user rights
-----------------------------

This operation searches the **ACLbit** backup database for effective user rights of
a user.

$ aclbit -U joe

Each row of the output displays user's effective rights on a file/directory.
The first column contains effective user rights of user *joe* in rwx
notation. The second column contains path to a file/directory to which
the rights apply.

A path is omitted from the output if the user's effective rights on it
are equal to the user's effective rights on its parent directory.

The output can look like the following.

--- /mnt/test
rwx /mnt/test/path/to/joes/place
r-x /mnt/test/path/to/readonly/joes/place

This can be read as that user *joe* has

- no access rights in /mnt/test and its subdirectories, except the following
- full access rights in /mnt/test/path/to/joes/place and its subdirectories
- readonly access rights in /mnt/test/path/to/readonly/joes/place and its subdirectories

The effective user rights are computed according to POSIX ACL
specification. The effective right is computed in the following order:

- If the user is the owner of file/directory, then owner's rights decide access.
- If the user is a named user in ACL of file/directory, then the named user's rights decide access.
- If the user is a member of the owning group of file/directory, then the owning group's rights decide access.
- If the user is a member of some named groups in ACL of file/directory, then the named groups' rights decide access (or on their rights).
- Otherwise other rights decide access.


Inspect group
-------------

This operation searches the **ACLbit** database for files/directories
with an ACL entry regarding a group. It does not distinguish between
owning and named groups.

$ aclbit -G smbusers

Each row of the output displays group's effective rights on
a file/directory. The first column contains effective rights of group
*smbusers* in rwx notation. The second column contains path to
a file/directory to which the rights apply.

A path is omitted from the output if the group's effective rights on it
equal to group's effective rights on its parent directory.

The output can look like the following.

--- /mnt/test
rwx /mnt/test/shares

This can be read as that user *smbusers* has

- no access rights in /mnt/test and its subdirectories, except the following
- full access rights in /mnt/test/shares and its subdirectories

This does not mean that all users from *smbusers* group have such access
rights. It only means that *smbusers* group has such access rights, not
concerning what rights are assigned to the members of the group.


Inspect file
------------

This operation dumps the ACL of a file/directory in the same format as
getfacl, but the information is retrieved from the **ACLbit** backup
database. It can either dump ACL of a file/directory itself or it can
dump ACLs of a directory and its subdirectories.

Nonrecursive.

$ aclbit -F /mnt/test/path/to/something

Recursive.

$ aclbit -F /mnt/test/path/to/something --recursive


Restore
-------

This operation restores a backed up ACL. It can either restore an ACL
for a single file/directory or it can restore ACLs for a directory and
its subdirectories.

Nonrecursive.

$ aclbit --restore /mnt/test/restore/path

Recursive.

$ aclbit --restore /mnt/test/restore/path --recursive

The restore operations is a shorthand for applying setfacl to file
inspection. The examples above have the same result as.

Nonrecursive.

$ cd /mnt/test/restore/path
$ aclbit --F /mnt/test/restore/path | setfacl

Recursive.

$ cd /mnt/test/restore/path
$ aclbit --F /mnt/test/restore/path --recursive | setfacl


Dump
----

The dump operation works on backup roots only. It outputs the same as the
getfacl utility, but gets the information from **ACLbit** backup database.

Check ACLs backed up for /mnt/test. 

$ aclbit --dump /mnt/test

The dump operation is in fact a shorthand for recursive inspection of
a backup root. So the following gives the same result.

$ aclbit -F /mnt/test --recursive

The output of this command should be equal to running the following
command in the time of backup of /mnt/test (without --files option).

$ cd /mnt/test
$ find . -type -d | getfacl --access -- -


Roots
-----

Use the roots operation to print all backup roots stored in **ACLbit**
backup database.

$ aclbit --roots


Remove root
-----------

This operation removes all ACLs backed up in **ACLbit** backup database
for a backup root.

This removes the /mnt/test backup root and all associated ACLs from 
**ACLbit** backup database.

$ aclbit --remove /mnt/test


Advanced Usage
==============

The **ACLbit** database is a SQLite3 relational database. As such it can be
queried ad hoc with **sqlite3** command line tool. The **ACLbit** database is
organized as follows.

As to keep the database as small as possible the access rights, user
ids, and group ids are stored as numbers. 

The access rights are represented as usual: as a logical OR of r (4),
w (2), and x (1). So that full access right is represented as 7.

The owner and group ids are retrieved using the **getent** utility which
returns the current users or groups according to nsswitch.conf settings.

The **ACLbit** database comprises three tables.

- root
- file
- entry

The *root* table stores backup roots.

|---------------------------------------------------------
| Column    | Type    | Meaning
|---------------------------------------------------------
| root_id   | INTEGER | Unique id of a backup root.
| root_path | TEXT    | Absolute path to the backup root.

The *file* table stores basic information about a file/directory ACL.

|---------------------------------------------------------
| Column        | Type    | Meaning
|---------------------------------------------------------
| file_id       | INTEGER | Unique id of a file. 
| file          | TEXT    | Relative path to a file from the backup root with '/' prepanded and appended. The backup root is represented with '/'. 
| root_id       | INTEGER | References id of a backup root.
| owner_id      | INTEGER | Id of the file owner according to getent passwd.
| group_id      | INTEGER | Id of the file owning group according to getent group.
| mask_rights   | INTEGER | Content of the mask::??? ACL entry.
| other_rights  | INTEGER | Content of the other::??? ACL entry.

The *entry* table stores individual ACL entries except mask:: and
other::.

|---------------------------------------------------------
| Column        | Type    | Meaning
|---------------------------------------------------------
| file_id       | INTEGER | References id of a file this ACL entry belongs to. 
| user_id       | INTEGER | Id of a user or a group this ACL entry reffers to. It can be either owner, named user, owning group or named group id.
| is_user       | INTEGER | 1 if user_id contains id of a user, 0 if user_id contains id of a group.
| rights        | INTEGER | ACL entry rights *without* mask applied.


Links
=====

- "Using ACLs with Fedora Core 2":http://www.vanemery.com/Linux/ACL/linux-acl.html
- "POSIX Access Control Lists on Linux":http://www.suse.de/~agruen/acl/linux-acls/online/
- "getfacl man page":http://www.linuxcommand.org/man_pages/getfacl1.html
- "setfacl man page":http://www.linuxcommand.org/man_pages/setfacl1.html
- "star archiver":http://cdrecord.berlios.de/old/private/star.html