1please.ini(5)                     User Manual                    please.ini(5)
2
3
4

NAME

6       please.ini - configuration file for access
7

DESCRIPTION

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

SECTION OPTIONS

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

MATCHES

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

ACTIONS

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

EXAMPLES

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

EXITCMD

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

DATED RANGES

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

DATEMATCHES

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

REASONS

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

DIR

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

LAST

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

SYSLOG

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

FILES

379       /etc/please.ini
380

NOTES

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

CONTRIBUTIONS

389       I welcome pull requests with open arms.  New  features  always  consid‐
390       ered.
391

BUGS

393       Found a bug?  Please either open a ticket or send a pull request/patch.
394

SEE ALSO

396       please(1)
397

AUTHORS

399       Ed Neville (ed-please@s5h.net).
400
401
402
403please 0.5.0                   07 November 2021                  please.ini(5)
Impressum