ACL implementation in docman

ACL implementation in docman is called trustees. It's based on concept of trustees for Linux kernel by Vyacheslav Zavadsky <zavadsky@braysystems.com>

Trustees are used to control access right, and special features (like notify on change)

For each path (which can be file or directory) all trustees are evaluated. However, deny has precedence over allow (which is default in no trustee is specified).

Format of trustee file

Comments are written using hash (#) as first character in line
# this is a comment

Group can be used instead of user-name in all ACL. You can't have user which has same name as group or vice-versa. It's written using plus (+) as first character in line.
+group:user[,user...]

ACL is defined
path[file]:(user|+group|*)[,user...]:[modifier]permission[:...]

Valid modifiers:

! trustee applies to all except user or group
C clear the permission (default is to set)
D deny access (default is grant)
O one-level trustee only (this means that those permissions will not be inherited on directories and files downwards from current level -- it's useful for anonymous access)

Valid permissions:

R read (file)
W write (file)
B browse (directory)
N notify (e-mail change)

Examples

# dpavlin is administrator (grant all access to members of root group)
+root:dpavlin
/:root:RWB
# give read-only access to all users
/:*:R
# anyone can write in this file
/public_write.txt:*:w
# let just joe access secret file
/secret:joe:!CRW

There is major difference between deny and clear. If you want to deny access to one file except to use joe (which should have read-only access) you could write:

/secret.txt:*:DRWB:joe:R

That is wrong. deny rules will take precedence over allow read to joe. So, you should write:

/secret.txt:*:CRWB:joe:R

Which will work.

If you want to allow just one user (editor) to have write persmissions on file one_editor.txt while all others can read it, you could do something like:

/one_editor.txt:*:DW:editor:CRWB

Order of statements is not important. Trustees are always evaluated from universal ones (e.g. ones for all users; with *) to specific for this user (in this case, for user editor). However, this example wouldn't work without C for user editor because deny for write would have precidence.

FIX write more examples, better descriptions...

Anonymous access

One of great advantages of using trustees is that you can allow anonymous access (without login). You should pay attention to access right, because you probably don't want anonymous users to see all files or folders in your repository.

First, you will have to add browse trustee to anonymous user on root directory -- docman will ignore all anonymous users if you don't do this.

	/:anonymous:BO

You really want to use flags BO and not just B because if you specify just B anonymous users will be able to browse (see directory names) of your whole repository. This way you can explicitly allow (or deny) which sub-directories you want anonymous users to browse.
For example, this will allow anonymous users to see and read everything in /pub and to store documents in /incoming:

	/pub:anonymous:RB
	/incoming:anonymous:RWB

You might also want to hide some directory from anonymous users, and you can do that using:

	/private:anonymous:DB

If you would like to give all your users which are authenticated via login and password all access to all files (like in old docman v1.x) you also have to add

	/:*:RWB

However, that will not add all permission to anonymous users. If you want to add all that permission to anonymous users (which will create wiki-like community for sharing files) you must explicitly say that you allow that to anonymous users:

	/:anonymous:RWB

All those setting will create environment which is very like docman v1.x, but with anonymous users allowed to see document in /pub and upload them in /incoming.

Default security

If none of trustee rules satisfy, default policy is deny. Basically, you have to explicitly allow all your users access to files (which can be as simple as /:*:RB to give read and browse to all users)

docman without trustee configuration

If you don't have realm/http_virtual_host.trustee you will fall-back to default docman v1.x behavior: whole group will have all right on all files except anonymous users (which won't be able to login anyway).