1please.ini(5) User Manual please.ini(5)
2
3
4
6 please.ini - configuration file for access
7
9 The please.ini file contains one or more [sections] that hold ACL for
10 users of the please and pleaseedit programs.
11
12 please.ini is an ini file, sections can be named with a short descrip‐
13 tion of what the section provides. You may then find this helpful when
14 listing rights with please -l.
15
16 Rules are read and applied in the order they are presented in the con‐
17 figuration file. For example, if the user matches a permit rule to run
18 a command in an early section, but in a later section matches criteria
19 for a deny and no further matches, then the user will not be permitted
20 to run that command. The last match wins.
21
22 The properties permitted are described below and should appear at most
23 once per section. If a property is used more than once in a section,
24 the last one will be used.
25
27 [section-name]
28 section name, shown in list mode
29
30 include=[file]
31 read ini file, and continue to next section
32
33 includedir=[directory]
34 read .ini files in directory, and continue to next section
35
37 name=[regex]
38 mandatory, the user or group (see below) to match against
39
40 target=[regex]
41 user to execute or list as, defaults to root
42
43 rule=[regex]
44 the regular expression that the command or edit path matches
45 against, defaults to ^$
46
47 notbefore=[YYYYmmdd|YYYYmmddHHMMSS]
48 will add HHMMSS as 00:00:00 to the date if not given, defaults
49 to never
50
51 notafter=[YYYYmmdd|YYYYmmddHHMMSS]
52 will add 23:59:59 to the date if not given, defaults to never
53
54 datematch=[Day dd Mon HH:MM:SS UTC YYYY]
55 regex to match a date string with
56
57 type=[edit/run/list]
58 this section’s mode behaviour, defaults to run, edit = pleaseed‐
59 it entry, list = user access rights listing
60
61 group=[true|false]
62 defaults to false, when true, the name (above) refers to a group
63 rather than a user
64
65 hostname=[regex]
66 permitted hostnames where this may apply. A hostname defined as
67 any or localhost will always match. Defaults to localhost
68
69 dir=[regex]
70 permitted directories to run within
71
72 permit_env=[regex]
73 allow environments that match regex to optionally pass through
74
75 regex is a regular expression, %{USER} will expand to the user who is
76 currently running please. This enables a single rule for a group to
77 modify/run something that matches their name.
78
79 Spaces within arguments will be substituted as `\ ' (backslash space).
80 Use ^/bin/echo hello\\ world$ to match /bin/echo “hello world”, note
81 that \ is a regex escape character so it must be escaped, therefore
82 matching a space becomes `\\ ' (backslash backslash space).
83
84 To match a \ (backslash), the hex code \x5c can be used.
85
86 To match the string %{USER}, the sequence \x25\{USER\} can be used.
87
88 Rules starting exact are string matches and not regex processed.
89
90 exact_name=[string]
91 only permit a user/group name that matches exactly
92
93 exact_hostname=[string]
94 only permit a hostname that matches exactly
95
96 exact_target=[string]
97 only permit a target that matches exactly
98
99 exact_rule=[string]
100 only permit a command rule that matches exactly
101
102 exact_dir=[string]
103 only permit a dir that matches exactly
104
106 permit=[true|false]
107 permit or disallow the entry, defaults to true
108
109 require_pass=[true|false]
110 if entry matches, require a password, defaults to true
111
112 reason=[true|false]
113 require a reason for execution/edit, defaults to false
114
115 last=[true|false]
116 if true, stop processing when entry is matched, defaults to
117 false
118
119 syslog=[true|false]
120 log this activity to syslog, defaults to true
121
122 env_assign.[key]=[value]
123 assign value to environment key
124
125 editmode=[octal mode|keep]
126 (type=edit) set the file mode bits on replacement file to octal
127 mode. When set to keep use the existing file mode. If the file
128 is not present, or mode is not declared, then mode falls back to
129 0600. If there is a file present, then the mode is read and
130 used just prior to file rename.
131
132 exitcmd=[program]
133 (type=edit) run program after editor exits as the target user,
134 if exit is zero, continue with file replacement. %{NEW} and
135 %{OLD} placeholders expand to new and old edit files
136
138 To allow all commands, you can use a greedy match (^.*$). You should
139 reduce this to the set of acceptable commands though.
140
141 [user_jim_root]
142 name=jim
143 target=root
144 rule=^.*$
145
146 If you wish to permit a user to view another’s command set, then you
147 may do this using type=list (run by default). To list another user,
148 they must match the target regex.
149
150 [user_jim_list_root]
151 name=jim
152 type=list
153 target=root
154
155 type may also be edit if you wish to permit a file edit with pleaseed‐
156 it.
157
158 [user_jim_edit_hosts]
159 name=jim
160 type=edit
161 target=root
162 rule=^/etc/hosts$
163
164 Naming sections should help later when listing permissions.
165
166 Below, user mandy may run du without needing a password, but must enter
167 her password for a bash running as root:
168
169 [mandy_du]
170 name = mandy
171 rule = ^(/usr)?/bin/du .*$
172 require_pass = false
173 [mandy_some]
174 name = mandy
175 rule = ^(/usr)?/bin/bash$
176 require_pass = true
177
178 The rule regex can include repetitions. To permit running wc to count
179 the lines in the log files (we don’t know how many there are) in
180 /var/log. This sort of regex will allow multiple instances of a ()
181 group with +, which is used to define the character class [a-zA-
182 Z0-9-]+, the numeric class and the group near the end of the line. In
183 other words, multiple instances of files in /var/log that may end in
184 common log rotate forms -YYYYMMDD or .N.
185
186 This will permit commands such as the following, note how for efficien‐
187 cy find will combine arguments with + into fewer invocations. xargs
188 could have been used in place of find.
189
190 $ find /var/log -type f -exec please /usr/bin/wc {} \+
191
192 Here is a sample for the above scenario:
193
194 [user_jim_root_wc]
195 name=jim
196 target=root
197 permit=true
198 rule=^/usr/bin/wc (/var/log/[a-zA-Z0-9-]+(\.\d+)?(\s)?)+$
199
200 User jim may only start or stop a docker container:
201
202 [user_jim_root_docker]
203 name=jim
204 target=root
205 permit=true
206 rule=^/usr/bin/docker (start|stop) \S+
207
208 User ben may only edit /etc/fstab:
209
210 [ben_fstab]
211 name=ben
212 target=root
213 permit=true
214 type=edit
215 rule=^/etc/fstab$
216
217 User ben may list only users eng, net and dba:
218
219 [ben_ops]
220 name=ben
221 permit=true
222 type=list
223 target=^(eng|net|dba)ops$
224
225 All users may list their own permissions. You may or may not wish to
226 do this if you consider permitting a view of the rules to be a security
227 risk.
228
229 [list_own]
230 name=^%{USER}$
231 permit=true
232 type=list
233 target=^%{USER}$
234
236 When the user completes their edit, and the editor exits cleanly, if
237 exitcmd is included then this program will run as the target user. If
238 the program also exits cleanly then the temporary edit will be copied
239 to the destination.
240
241 %{OLD} and %{NEW} will expand to the old (existing source) file and ed‐
242 it candidate, respectively. To verify a file edit, ben’s entry to
243 check /etc/hosts after clean exit could look like this:
244
245 [ben_ops]
246 name=ben
247 permit=true
248 type=edit
249 rule=^/etc/hosts$
250 exitcmd=/usr/local/bin/check_hosts %{OLD} %{NEW}
251
252 /usr/local/bin/check_hosts takes two arguments, the original file as
253 the first argument and the modify candidate as the second argument. If
254 check_hosts terminates zero, then the edit is considered clean and the
255 original file is replaced with the candidate. Otherwise the edit file
256 is not copied and is left, pleaseedit will exit with the return value
257 from check_hosts.
258
259 A common exitcmd is to check the validity of please.ini, shown below.
260 This permits members of the admin group to edit /etc/please.ini if they
261 provide a reason (-r). Upon clean exit from the editor the tmp file
262 will be syntax checked.
263
264 [please_ini]
265 name = admins
266 group = true
267 reason = true
268 rule = /etc/please.ini
269 type = edit
270 editmode = 600
271 exitcmd = /usr/bin/please -c %{NEW}
272
274 For large environments it is not unusual for a third party to require
275 access during a short time frame for debugging. To accommodate this
276 there are the notbefore and notafter time brackets. These can be ei‐
277 ther YYYYmmdd or YYYYmmddHHMMSS.
278
279 The whole day is considered when using the shorter date form of YYYYm‐
280 mdd.
281
282 Many enterprises may wish to permit periods of access to a user for a
283 limited time only, even if that individual is considered to have a per‐
284 manent role.
285
286 User joker can do what they want as root on 1st April 2021:
287
288 [joker_april_first]
289 name=joker
290 target=root
291 permit=true
292 notbefore=20210401
293 notafter=20210401
294 rule=^/bin/bash
295
297 datematch matches against the date string Day dd mon HH:MM:SS UTC Year.
298 This enables calendar style date matches.
299
300 Note that the day of the month (dd) will be padded with spaces if less
301 than two characters wide.
302
303 You can permit a group of users to run /usr/local/housekeeping/ scripts
304 every Monday:
305
306 [l2_housekeeping]
307 name=l2users
308 group=true
309 target=root
310 permit=true
311 rule = /usr/local/housekeeping/tidy_(logs|images|mail)
312 datematch = ^Mon\s+.*
313
315 When reason=true, require a reason before permitting edits or execution
316 with the -r option to please and pleaseedit. Some organisations may
317 prefer a reason to be logged when a command is executed. This can be
318 helpful for some situations where something such as mkfs or useradd
319 might be preferable to be logged against a ticket.
320
321 [l2_user_admin]
322 name=l2users
323 group=true
324 target=root
325 permit=true
326 reason=true
327 rule = ^/usr/sbin/useradd -m \w+$
328
329 Perhaps you want to add a mini mollyguard:
330
331 [user_poweroff]
332 name = l2users
333 group = true
334 rule = (/usr)?/s?bin/(shutdown( -h now)?|poweroff|reboot)
335 require_pass = true
336 reason = true
337
339 In some situations you may only want a command to run within a set of
340 directories. The directory is specified with the -d argument to
341 please. For example, a program may output to the current working di‐
342 rectory, which may only be desirable in certain locations.
343
344 [eng_build_aliases]
345 name=l2users
346 group=true
347 dir=^/etc/mail$
348 rule = ^/usr/local/bin/build_aliases$
349
351 last=true stops processing at a match:
352
353 [mkfs]
354 name=l2users
355 group=true
356 target=root
357 permit=true
358 reason=true
359 rule = ^/sbin/mkfs.(ext[234]|xfs) /dev/sd[bcdefg]\d?$
360 last=true
361
362 For simplicity, there is no need to process other configured rules if
363 certain that the l2users group are safe to execute this. last should
364 only be used in situations where there will never be something that
365 could contradict the match in an undesired way later.
366
368 By default entries are logged to syslog. If you do not wish an entry
369 to be logged then specify syslog=false. In this case jim can run any‐
370 thing in /usr/bin/ as root and it will not be logged.
371
372 [maverick]
373 syslog = false
374 name = jim
375 rule = /usr/bin/.*
376 reason = false
377
379 /etc/please.ini
380
382 At a later date repeated properties within the same section may be
383 treated as a match list.
384
385 At a later date sections with names containing `default' may behave
386 differently to normal sections.
387
389 I welcome pull requests with open arms. New features always consid‐
390 ered.
391
393 Found a bug? Please either open a ticket or send a pull request/patch.
394
396 please(1)
397
399 Ed Neville (ed-please@s5h.net).
400
401
402
403please 0.5.0 07 November 2021 please.ini(5)