docman2/doc/trustee.html

<h1>ACL implementation in docman</h1>

<p>ACL implementation in docman is called <b>trustees</b>. It's based on
concept of trustees for Linux kernel by Vyacheslav Zavadsky
&lt;zavadsky@braysystems.com&gt;
</p>

<p>Trustees are used to control access right, and special features
(like <a href="notify.html">notify on change</a>)
</p>

<h2>Format of trustee file</h2>

<p>Comments are written using hash (#) as first character in line
<br><tt># this is a comment</tt></p>

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

<p>ACL is defined
<br><i>path</i>[<i>file</i>]<b>:</b>(<i>user</i>|<i>+group</i>|*)[,<i>user</i>...]:[<i>modifier</i>]<i>permission</i>[:...]</p>

Valid modifiers:
<ul>
<li><tt>!</tt> trustee applies to all except user or group
<li><tt>C</tt> clear the permission (default is to set)
<li><tt>D</tt> deny access (default is grant)
<li><tt>O</tt> one-level trustee only <small>(this means that those permissions
        will not be inherited on directories and files upwards from current
        level -- it's usefull for root directory only anonymous access)
</ul>

Valid permissions:
<ul>
<li><tt>R</tt> read (file)
<li><tt>W</tt> write (file)
<li><tt>B</tt> browse (directory)
<li><tt>N</tt> <a href="notify.html">notify</a> (e-mail change)
</ul>

<h2>Examples</h2>

<pre>
# dpavlin is admin (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
</pre>

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

<pre>
/secret.txt:*:DRWB:joe:R
</pre>

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

<pre>
/secret.txt:*:CRWB:joe:R
</pre>

Which will work.

<big>FIX</big> write more examples, better descriptions...

<h2>Default security</h2>

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

<h2>docman without trustee configuration</h2>

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

<p>See also:
<a href="admin.html">Administration manual</a>
</p>
1	dpavlin	1.1	<h1>ACL implementation in docman</h1>
2
3			<p>ACL implementation in docman is called <b>trustees</b>. It's based on
4			concept of trustees for Linux kernel by Vyacheslav Zavadsky
5			<zavadsky@braysystems.com>
6			</p>
7
8	dpavlin	1.2	<p>Trustees are used to control access right, and special features
9			(like <a href="notify.html">notify on change</a>)
10	dpavlin	1.1	</p>
11
12			<h2>Format of trustee file</h2>
13
14			<p>Comments are written using hash (#) as first character in line
15			<br><tt># this is a comment</tt></p>
16
17			<p>Group can be used instead of username in all ACLs. You can't have user
18			which has same name as group or vice-versa. It's written using plus (+) as
19			first character in line.
20			<br>+<i>group</i>:<i>user</i>[,<i>user</i>...]</p>
21
22			<p>ACL is defined
23			<br><i>path</i>[<i>file</i>]<b>:</b>(<i>user</i>\|<i>+group</i>\|*)[,<i>user</i>...]:[<i>modifier</i>]<i>permission</i>[:...]</p>
24
25			Valid modifiers:
26			<ul>
27			<li><tt>!</tt> trustee applies to all except user or group
28	dpavlin	1.2	<li><tt>C</tt> clear the permission (default is to set)
29	dpavlin	1.1	<li><tt>D</tt> deny access (default is grant)
30	dpavlin	1.4	<li><tt>O</tt> one-level trustee only <small>(this means that those permissions
31			will not be inherited on directories and files upwards from current
32			level -- it's usefull for root directory only anonymous access)
33	dpavlin	1.1	</ul>
34
35			Valid permissions:
36			<ul>
37			<li><tt>R</tt> read (file)
38			<li><tt>W</tt> write (file)
39			<li><tt>B</tt> browse (directory)
40	dpavlin	1.2	<li><tt>N</tt> <a href="notify.html">notify</a> (e-mail change)
41	dpavlin	1.1	</ul>
42
43			<h2>Examples</h2>
44
45			<pre>
46			# dpavlin is admin (grant all access to members of root group)
47			+root:dpavlin
48			/:root:RWB
49			# give read-only access to all users
50			/:*:R
51			# anyone can write in this file
52			/public_write.txt:*:w
53			# let just joe access secret file
54			/secret:joe:!CRW
55			</pre>
56
57			<p>There is major difference between <b>deny</b> and <b>clear</b>. If you
58			want to deny access to one file except to use joe (which should have
59			read-only access) you could write:
60
61			<pre>
62			/secret.txt:*:DRWB:joe:R
63			</pre>
64
65	dpavlin	1.2	That is wrong. <b>deny</b> rules will take precedence over allow read
66	dpavlin	1.1	to joe. So, you should write:
67
68			<pre>
69			/secret.txt:*:CRWB:joe:R
70			</pre>
71
72			Which will work.
73
74	dpavlin	1.2	<big>FIX</big> write more examples, better descriptions...
75	dpavlin	1.1
76			<h2>Default security</h2>
77
78			<p>If none of trustee rules satisfy, default policy is <i>deny</i>. Basically,
79			you have to explicitly allow all your users access to files (which can be
80			as simple as <tt>/:*:RB</tt> to give <i>read</i> and <i>browse</i> to all
81			users)
82			</p>
83
84			<h2>docman without trustee configuration</h2>
85
86			<p>If you <b>don't have</b> <tt>realm/http_virtual_host.trustee</tt> you
87	dpavlin	1.2	will fall-back to default docman v1.x behavior: whole group will have
88	dpavlin	1.1	all right on all files except <i>anonymous</i> users (which won't be able
89			to login anyway).
90			</p>
91	dpavlin	1.3
92			<p>See also:
93			<a href="admin.html">Administration manual</a>
94			</p>