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