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 |
<p>Trustees are used to control access right, and special features |
9 |
(like <a href="notify.html">notify on change</a>) |
10 |
</p> |
11 |
|
12 |
<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 |
<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 |
<p>Group can be used instead of user-name in all ACL. You can't have user |
23 |
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 |
<li><tt>C</tt> clear the permission (default is to set) |
34 |
<li><tt>D</tt> deny access (default is grant) |
35 |
<li><tt>O</tt> one-level trustee only <small>(this means that those permissions |
36 |
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 |
</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 |
<li><tt>N</tt> <a href="notify.html">notify</a> (e-mail change) |
47 |
</ul> |
48 |
|
49 |
<h2>Examples</h2> |
50 |
|
51 |
<pre> |
52 |
# dpavlin is administrator (grant all access to members of root group) |
53 |
+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 |
That is wrong. <b>deny</b> rules will take precedence over allow read |
72 |
to joe. So, you should write: |
73 |
|
74 |
<pre> |
75 |
/secret.txt:*:CRWB:joe:R |
76 |
</pre> |
77 |
|
78 |
Which will work. |
79 |
|
80 |
<p>If you want to allow just one user (<i>editor</i>) to have write |
81 |
persmissions on file <i>one_editor.txt</i> while all others can read it, you |
82 |
could do something like: |
83 |
|
84 |
<pre> |
85 |
/one_editor.txt:*:DW:editor:CRWB |
86 |
</pre> |
87 |
|
88 |
Order of statements is not important. Trustees are always evaluated from |
89 |
universal ones (e.g. ones for all users; with *) to specific for this |
90 |
user (in this case, for user <i>editor</i>). However, this example |
91 |
wouldn't work without <b>C</b> for user <i>editor</i> because <b>deny</b> |
92 |
for write would have precidence. |
93 |
|
94 |
<p> |
95 |
<big>FIX</big> write more examples, better descriptions... |
96 |
</p> |
97 |
|
98 |
<a name="anonymous"> |
99 |
<h3>Anonymous access</h3> |
100 |
|
101 |
<p>One of great advantages of using trustees is that you can allow |
102 |
anonymous access (without login). You should pay attention to access |
103 |
right, because you probably don't want anonymous users to see all files |
104 |
or folders in your repository. |
105 |
</p> |
106 |
|
107 |
<p>First, you will have to add browse trustee to anonymous user |
108 |
on root directory -- docman will ignore all anonymous users if |
109 |
you don't do this. |
110 |
<pre> |
111 |
/:anonymous:BO |
112 |
</pre> |
113 |
You really <b>want to use flags <tt>BO</tt></b> and not just <tt>B</tt> because |
114 |
if you specify just <tt>B</tt> anonymous users will be able to browse (see |
115 |
directory names) of your whole repository. This way you can explicitly |
116 |
allow (or deny) which sub-directories you want anonymous users to browse. |
117 |
<br>For example, this will allow anonymous users to see and read everything |
118 |
in <tt>/pub</tt> and to store documents in <tt>/incoming</tt>: |
119 |
<pre> |
120 |
/pub:anonymous:RB |
121 |
/incoming:anonymous:RWB |
122 |
</pre> |
123 |
You might also want to hide some directory from anonymous users, and you |
124 |
can do that using: |
125 |
<pre> |
126 |
/private:anonymous:DB |
127 |
</pre> |
128 |
If you would like to <b>give all your users</b> which are authenticated via |
129 |
login and password <b>all access</b> to all files (like in old docman v1.x) you |
130 |
also have to add |
131 |
<pre> |
132 |
/:*:RWB |
133 |
</pre> |
134 |
However, that <b>will not add all |
135 |
permission to anonymous users</b>. If you want to add all that permission |
136 |
to anonymous users (which will create wiki-like community for sharing files) |
137 |
you must explicitly say that you allow that to anonymous users: |
138 |
<pre> |
139 |
/:anonymous:RWB |
140 |
</pre> |
141 |
All those setting will create environment which is very like docman v1.x, |
142 |
but with anonymous users allowed to see document in <tt>/pub</tt> and |
143 |
upload them in <tt>/incoming</tt>. |
144 |
</p> |
145 |
|
146 |
<h2>Default security</h2> |
147 |
|
148 |
<p>If none of trustee rules satisfy, default policy is <i>deny</i>. Basically, |
149 |
you have to explicitly allow all your users access to files (which can be |
150 |
as simple as <tt>/:*:RB</tt> to give <i>read</i> and <i>browse</i> to all |
151 |
users) |
152 |
</p> |
153 |
|
154 |
<h2>docman without trustee configuration</h2> |
155 |
|
156 |
<p>If you <b>don't have</b> <tt>realm/http_virtual_host.trustee</tt> you |
157 |
will fall-back to default docman v1.x behavior: whole group will have |
158 |
all right on all files except <i>anonymous</i> users (which won't be able |
159 |
to login anyway). |
160 |
</p> |
161 |
|
162 |
<p>See also: |
163 |
<a href="admin.html">Administration manual</a> |
164 |
</p> |