permissioner

1) # Permissioner: Setting File Ownerships and Permissions
2) 
3) The unix tools `chown` and `chmod` allow to set ownership and permissions of
4) files and entire directory trees. However, multiple calls to those tools
5) are needed when setting complex ownerships and permissions of nested directory
6) trees. In case the change of ownerships and permissions shall be very fast for
7) file, e.g., because the directory tree is accessed in parallel to the change,
8) using multiple calls is not suitable.
9) 
10) For example, let's assume, multiple users write files to a shared directory
11) `shared/` in order to implement a primitive ad-hoc file sharing. The users
12) all have the group `fileshare`. All files copied to the shared directory
13) shall be readable, writable and deletable by all other users in the group.
14) However, there is one directory, called `shared/perm`, in which files should
15) stay permanently and be only readable for all users. This could be implemented
16) by executing the following commands periodically in a `cron`-job:
17) 
18) ```
19) chown -R nobody:fileshare shared
20) chmod -R ug+rwX shared
21) chmod -R g-w shared/perm
22) ```
23) 
24) However, while the sequence of the three commands is executing, strange and
25) unwanted ownerships and permissions may occur. If the directory tree is large,
26) it can lead to problems accessing the files in parallel.
27) 
28) Permissioner can help to reduce the problems by touching each file only once,
29) and setting its ownership and permissions very quickly, before advancing to the
30) next file.
31) 
32) Using the configuration file `fileshare.cfg` with the content
33) 
34) ```
35) tree nobody fileshare ug+rwX shared
36) tree nobody fileshare u+rwX,g+wX,g-w shared/perm
37) ```
38) 
39) in the call
40) 
41) ```
42) bin/permissionerc fileshare.cfg
43) ```
44) 
45) has the same effect, but achieves the same outcome while touching every file
46) just once - thus avoiding the transient strange state of files.
47) 
48) This is only a simple example to illustrate the functionality of
49) permissioner. There are various other tools to properly implement a file
50) sharing service. The sketched setup is only an ad-hoc hack and not a proper
51) solution.
52) 
53) Situations in which `chown` and `chmod` are not sufficient are no very common.
54) Thus, permissioner is a very specific tool for a very specific use case. If
55) you are not sure if you should use permissioner, after reading the above
56) example, you should probably stick with the Unix tools `chown` and `chmod`.
57) 
58) ## Building
59) 
60) Permissioner is developed on Debian Linux 10 "buster".
61) 
62) Install the dependencies:
63) 
64) ```
65) apt-get install -y build-essential cmake gcc g++ ninja-build \
66) ```
67) 
68) Change to the directory of this `REAMDE.md` file.
69) 
70) Configure a build directory:
71) 
72) ```
73) mkdir build
74) cd build
75) cmake -G Ninja -D CMAKE_BUILD_TYPE=Release ..
76) ```
77) 
78) Build:
79) 
80) ```
81) ninja
82) ```
83) 
84) Run tests:
85) 
86) ```
87) ctest
88) ```
89) 
90) ## Config File
91) 
92) The configuration file lists directory trees and the ownerships and permissions
93) to set for them. If some of the specified trees are nested within each other,
94) the nested tree(s) is/are excluded from the containing tree(s).
95) 

96) The syntax of the config file is line-based. Each line defines a setting or a
97) directory tree and the ownerships and permissions for it.

98) 
99) Syntax:
100) 

101)    * process nice-ness (only for `permissionerd`, ignored by `permissonerc`)
102)      `nice [<niceness value>] [idle]
103)       * `<niceness value>`: Linux niceness value for daemon process,
104)                             `19` for nicest (lowest CPU priority)
105)       * `idle`: set I/O priority class to idle

106)    * sleep time after each file: `sleepTime <seconds>`
107)       * range 0 - 1 s, default 1e-6 s
108)    * wait time factor: `waitFactor <floating-point factor>`
109)       * how long to wait after each tree traversal relative to the duration of
110)         the traversal
111)       * range 0 - 1000, default 10
112)    * additional wait time after each tree traversal: `waitTime <seconds>`
113)       * range 0 - 3600 s, default 1 s

114)    * owership and permission configuration:
115)      `tree <user> <group> <permissions> <directory>`
116)       * `<user>`: User name to set as user/owner, `-` to not change the user/owner.
117)       * `<group>`: Group name to set as group, `-` to not change the group.
118)       * `<permissions>`: Comma-separated list of permission settings.
119)          * `<perm setting>[,<perm setting>[,<...>]]`
120)       * `<perm setting>`: Setting (`=`), adding (`+`) or removing (`-`) permissions.
121)          * `<who>[=+-]<what>`
122)       * `<who>`: For whom to change the permissions. Any combination of:
123)          * `u`: User.
124)          * `g`: Group.
125)          * `o`: Others.
126)       * `<what>`: Which permissions to change.
127)          * `r`: Reading.
128)          * `w`: Writing.
129)          * `x`: Executing for files, browsing for directories.
130)          * `X`: Like `x` if `x` set for user/owner of the file.
131)       * `<directory>`: Absolute or relative directory name.
132)          * Defines the base of a directory tree to process.
133)          * Relative directory names are relative to the woking directory of
134)            `permissionerc` or `permissionerd`.