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>

<p>For each path (which can be file or directory) all trustees are
evaluated. However, <b>deny</b> has precedence over <b>allow</b> (which
is default in no trustee is specified).
</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 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.
<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 downwards from current
        level -- it's useful for <a href="#anonymous">anonymous access</a>)
        </small>
</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 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
</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...

<a name="anonymous">
<h3>Anonymous access</h3>

<p>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.
</p>

<p>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.
<pre>
        /:anonymous:BO
</pre>
You really <b>want to use flags <tt>BO</tt></b> and not just <tt>B</tt> because
if you specify just <tt>B</tt> 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.
<br>For example, this will allow anonymous users to see and read everything
in <tt>/pub</tt> and to store documents in <tt>/incoming</tt>:
<pre>
        /pub:anonymous:RB
        /incoming:anonymous:RWB
</pre>
You might also want to hide some directory from anonymous users, and you
can do that using:
<pre>
        /private:anonymous:DB
</pre>
If you would like to <b>give all your users</b> which are authenticated via
login and password <b>all access</b> to all files (like in old docman v1.x) you
also have to add 
<pre>
        /:*:RWB
</pre>
However, that <b>will not add all
permission to anonymous users</b>. 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:
<pre>
        /:anonymous:RWB
</pre>
All those setting will create environment which is very like docman v1.x,
but with anonymous users allowed to see document in <tt>/pub</tt> and
upload them in <tt>/incoming</tt>.
</p>

<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	dpavlin	1.7	<p>For each path (which can be file or directory) all trustees are
13			evaluated. However, <b>deny</b> has precedence over <b>allow</b> (which
14			is default in no trustee is specified).
15			</p>
16
17	dpavlin	1.1	<h2>Format of trustee file</h2>
18
19			<p>Comments are written using hash (#) as first character in line
20			<br><tt># this is a comment</tt></p>
21
22	dpavlin	1.5	<p>Group can be used instead of user-name in all ACL. You can't have user
23	dpavlin	1.1	which has same name as group or vice-versa. It's written using plus (+) as
24			first character in line.
25			<br>+<i>group</i>:<i>user</i>[,<i>user</i>...]</p>
26
27			<p>ACL is defined
28			<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>
29
30			Valid modifiers:
31			<ul>
32			<li><tt>!</tt> trustee applies to all except user or group
33	dpavlin	1.2	<li><tt>C</tt> clear the permission (default is to set)
34	dpavlin	1.1	<li><tt>D</tt> deny access (default is grant)
35	dpavlin	1.4	<li><tt>O</tt> one-level trustee only <small>(this means that those permissions
36	dpavlin	1.5	will not be inherited on directories and files downwards from current
37			level -- it's useful for <a href="#anonymous">anonymous access</a>)
38			</small>
39	dpavlin	1.1	</ul>
40
41			Valid permissions:
42			<ul>
43			<li><tt>R</tt> read (file)
44			<li><tt>W</tt> write (file)
45			<li><tt>B</tt> browse (directory)
46	dpavlin	1.2	<li><tt>N</tt> <a href="notify.html">notify</a> (e-mail change)
47	dpavlin	1.1	</ul>
48
49			<h2>Examples</h2>
50
51			<pre>
52	dpavlin	1.5	# dpavlin is administrator (grant all access to members of root group)
53	dpavlin	1.1	+root:dpavlin
54			/:root:RWB
55			# give read-only access to all users
56			/:*:R
57			# anyone can write in this file
58			/public_write.txt:*:w
59			# let just joe access secret file
60			/secret:joe:!CRW
61			</pre>
62
63			<p>There is major difference between <b>deny</b> and <b>clear</b>. If you
64			want to deny access to one file except to use joe (which should have
65			read-only access) you could write:
66
67			<pre>
68			/secret.txt:*:DRWB:joe:R
69			</pre>
70
71	dpavlin	1.2	That is wrong. <b>deny</b> rules will take precedence over allow read
72	dpavlin	1.1	to joe. So, you should write:
73
74			<pre>
75			/secret.txt:*:CRWB:joe:R
76			</pre>
77
78			Which will work.
79
80	dpavlin	1.2	<big>FIX</big> write more examples, better descriptions...
81	dpavlin	1.5
82			<a name="anonymous">
83			<h3>Anonymous access</h3>
84
85			<p>One of great advantages of using trustees is that you can allow
86			anonymous access (without login). You should pay attention to access
87			right, because you probably don't want anonymous users to see all files
88			or folders in your repository.
89			</p>
90
91			<p>First, you will have to add browse trustee to anonymous user
92			on root directory -- docman will ignore all anonymous users if
93			you don't do this.
94			<pre>
95			/:anonymous:BO
96			</pre>
97			You really <b>want to use flags <tt>BO</tt></b> and not just <tt>B</tt> because
98			if you specify just <tt>B</tt> anonymous users will be able to browse (see
99			directory names) of your whole repository. This way you can explicitly
100			allow (or deny) which sub-directories you want anonymous users to browse.
101			<br>For example, this will allow anonymous users to see and read everything
102			in <tt>/pub</tt> and to store documents in <tt>/incoming</tt>:
103			<pre>
104			/pub:anonymous:RB
105			/incoming:anonymous:RWB
106			</pre>
107			You might also want to hide some directory from anonymous users, and you
108			can do that using:
109			<pre>
110			/private:anonymous:DB
111			</pre>
112	dpavlin	1.7	If you would like to <b>give all your users</b> which are authenticated via
113	dpavlin	1.6	login and password <b>all access</b> to all files (like in old docman v1.x) you
114			also have to add
115			<pre>
116			/:*:RWB
117			</pre>
118			However, that <b>will not add all
119			permission to anonymous users</b>. If you want to add all that permission
120	dpavlin	1.7	to anonymous users (which will create wiki-like community for sharing files)
121	dpavlin	1.6	you must explicitly say that you allow that to anonymous users:
122			<pre>
123			/:anonymous:RWB
124			</pre>
125	dpavlin	1.7	All those setting will create environment which is very like docman v1.x,
126	dpavlin	1.6	but with anonymous users allowed to see document in <tt>/pub</tt> and
127			upload them in <tt>/incoming</tt>.
128	dpavlin	1.5	</p>
129	dpavlin	1.1
130			<h2>Default security</h2>
131
132			<p>If none of trustee rules satisfy, default policy is <i>deny</i>. Basically,
133			you have to explicitly allow all your users access to files (which can be
134			as simple as <tt>/:*:RB</tt> to give <i>read</i> and <i>browse</i> to all
135			users)
136			</p>
137
138			<h2>docman without trustee configuration</h2>
139
140			<p>If you <b>don't have</b> <tt>realm/http_virtual_host.trustee</tt> you
141	dpavlin	1.2	will fall-back to default docman v1.x behavior: whole group will have
142	dpavlin	1.1	all right on all files except <i>anonymous</i> users (which won't be able
143			to login anyway).
144			</p>
145	dpavlin	1.3
146			<p>See also:
147			<a href="admin.html">Administration manual</a>
148			</p>