.\" Automatically generated by Pandoc 2.17.1.1
.\"
.\" Define V font for inline verbatim, using C font in formats
.\" that render this, and otherwise B font.
.ie "\f[CB]x\f[]"x" \{\
. ftr V B
. ftr VI BI
. ftr VB B
. ftr VBI BI
.\}
.el \{\
. ftr V CR
. ftr VI CI
. ftr VB CB
. ftr VBI CBI
.\}
.TH "please.ini" "5" "06 September 2024" "please 0.5.6" "User Manual"
.hy
.SH NAME
.PP
please.ini - configuration file for access
.SH DESCRIPTION
.PP
The \f[B]please.ini\f[R] file contains one or more \f[B][sections]\f[R]
that hold ACL for users of the \f[B]please\f[R] and \f[B]pleaseedit\f[R]
programs.
.PP
\f[V]please.ini\f[R] is an ini file, sections can be named with a short
description of what the section provides.
You may then find this helpful when listing rights with \f[B]please
-l\f[R].
.PP
Rules are read and applied in the order they are presented in the
configuration file.
For example, if the user matches a permit rule to run a command in an
early section, but in a later section matches criteria for a deny and no
further matches, then the user will not be permitted to run that
command.
The last match wins.
.PP
The properties permitted are described below and should appear at most
once per section.
If a property is used more than once in a section, the last one will be
used.
.SH SECTION OPTIONS
.TP
\f[B][section-name]\f[R]
section name, shown in list mode
.TP
\f[B]include=[file]\f[R]
read ini file, and continue to next section
.TP
\f[B]includedir=[directory]\f[R]
read .ini files in directory, and continue to next section, if the
directory does not exist config parse will fail
.PP
Sections with a name starting \f[B]default\f[R] will retain match
actions including implicit \f[B]permit\f[R], therefore setting
\f[B]permit=false\f[R] in the default block and \f[B]permit=true\f[R]
elsewhere is advised.
.SH MATCHES
.TP
\f[B]name=[regex]\f[R]
mandatory, the user or \f[B]group\f[R] (see below) to match against
.TP
\f[B]target=[regex]\f[R]
user to execute or list as, defaults to \f[B]root\f[R]
.TP
\f[B]target_group=[regex]\f[R]
requires that the user runs with \f[B]--group\f[R] to run or edit with
the match
.TP
\f[B]rule=[regex]\f[R]
the regular expression that the command or edit path matches against,
defaults to \[ha]$
.TP
\f[B]notbefore=[YYYYmmdd|YYYYmmddHHMMSS]\f[R]
will add HHMMSS as 00:00:00 to the date if not given, defaults to never
.TP
\f[B]notafter=[YYYYmmdd|YYYYmmddHHMMSS]\f[R]
will add 23:59:59 to the date if not given, defaults to never
.TP
\f[B]datematch=[Day dd Mon HH:MM:SS UTC YYYY]\f[R]
regex to match a date string with
.TP
\f[B]type=[edit/run/list]\f[R]
this section\[cq]s mode behaviour, defaults to \f[B]run\f[R], edit =
\f[B]pleaseedit\f[R] entry, list = user access rights listing
.TP
\f[B]group=[true|false]\f[R]
defaults to false, when true, the \f[B]name\f[R] (above) refers to a
group rather than a user
.TP
\f[B]hostname=[regex]\f[R]
permitted hostnames where this may apply.
A hostname defined as \f[B]any\f[R] or \f[B]localhost\f[R] will always
match.
Defaults to localhost
.TP
\f[B]dir=[regex]\f[R]
permitted directories to run within
.TP
\f[B]permit_env=[regex]\f[R]
allow environments that match \f[B]regex\f[R] to optionally pass through
.TP
\f[B]search_path=[string]\f[R]
configure a \f[B]:\f[R] separated directory list to locate the binary to
execute, does not configure a \f[B]PATH\f[R] environment and is searched
as the user running \f[B]please\f[R], not as the \f[B]target\f[R] user
(no plans to change that at present)
.PP
\f[B]regex\f[R] is a regular expression, \f[B]%{USER}\f[R] will expand
to the user who is currently running \f[V]please\f[R],
\f[B]%{HOSTNAME}\f[R] expands to the hostname.
See below for examples.
Other \f[B]%{}\f[R] expansions may be added at a later date.
.PP
Spaces within arguments will be substituted as \f[B]`\[rs]\ '\f[R]
(backslash space).
Use \f[B]\[ha]/bin/echo hello\[rs]\[rs] world$\f[R] to match
\f[B]/bin/echo \[lq]hello world\[rq]\f[R], note that \f[B]\[rs]\f[R] is
a regex escape character so it must be escaped, therefore matching a
space becomes \f[B]`\[rs]\[rs]\ '\f[R] (backslash backslash space).
.PP
To match a \f[B]\[rs]\f[R] (backslash), the hex code \f[B]\[rs]x5c\f[R]
can be used.
.PP
To match the string \f[B]%{USER}\f[R], the sequence
\f[B]\[rs]x25\[rs]{USER\[rs]}\f[R] can be used.
.PP
Rules starting \f[B]exact\f[R] are string matches and not
\f[B]regex\f[R] processed and take precedence over \f[B]regex\f[R]
matches.
.TP
\f[B]exact_name=[string]\f[R]
only permit a user/group name that matches exactly
.TP
\f[B]exact_hostname=[string]\f[R]
only permit a hostname that matches exactly
.TP
\f[B]exact_target=[string]\f[R]
only permit a target that matches exactly
.TP
\f[B]exact_target_group=[groupname]\f[R]
requires that the user runs with \f[B]--group\f[R] to run or edit as
\f[B]groupname\f[R]
.TP
\f[B]exact_rule=[string]\f[R]
only permit a command rule that matches exactly
.TP
\f[B]exact_dir=[string]\f[R]
only permit a dir that matches exactly
.SH ACTIONS
.TP
\f[B]permit=[true|false]\f[R]
permit or disallow the entry, defaults to true
.TP
\f[B]require_pass=[true|false]\f[R]
if entry matches, require a password, defaults to true
.TP
\f[B]timeout=[number]\f[R]
length of timeout in whole seconds to wait for password input
.TP
\f[B]last=[true|false]\f[R]
if true, stop processing when entry is matched, defaults to false
.TP
\f[B]reason=[true|false|regex]\f[R]
require a reason for execution/edit.
If reason is \f[B]true\f[R] then any reason will satisfy.
Any string other than \f[B]true\f[R] or \f[B]false\f[R] will be treated
as a regex match.
Defaults to false
.TP
\f[B]token_timeout=[number]\f[R]
length of timeout for token authentication in whole seconds (default
600)
.TP
\f[B]syslog=[true|false]\f[R]
log this activity to syslog, defaults to true
.TP
\f[B]env_assign.[key]=[value]\f[R]
assign \f[B]value\f[R] to environment \f[B]key\f[R]
.TP
\f[B]editmode=[octal mode|keep]\f[R]
(\f[B]type=edit\f[R]) set the file mode bits on replacement file to
octal mode.
When set to \f[B]keep\f[R] use the existing file mode.
If the file is not present, or mode is not declared, then mode falls
back to 0600.
If there is a file present, then the mode is read and used just prior to
file rename
.TP
\f[B]exitcmd=[program]\f[R]
(\f[B]type=edit\f[R]) run program after editor exits as the target user,
if exit is zero, continue with file replacement.
\f[B]%{NEW}\f[R] and \f[B]%{OLD}\f[R] placeholders expand to new and old
edit files
.SH EXAMPLES
.PP
To allow all commands, you can use a greedy match (\f[B]\[ha].*$\f[R]).
You should reduce this to the set of acceptable commands though.
.IP
.nf
\f[C]
[user_jim_root]
name = jim
target = root
rule = \[ha].*$
\f[R]
.fi
.PP
If you wish to permit a user to view another\[cq]s command set, then you
may do this using \f[B]type=list\f[R] (\f[B]run\f[R] by default).
To list another user, they must match the \f[B]target\f[R] regex.
.IP
.nf
\f[C]
[user_jim_list_root]
name = jim
type = list
target = root
\f[R]
.fi
.PP
\f[B]type\f[R] may also be \f[B]edit\f[R] if you wish to permit a file
edit with \f[B]pleaseedit\f[R].
.IP
.nf
\f[C]
[user_jim_edit_hosts]
name = jim
type = edit
target = root
rule = \[ha]/etc/hosts$
editmode = 644
\f[R]
.fi
.PP
Naming sections should help later when listing permissions.
.PP
Below, user \f[B]mandy\f[R] may run \f[B]du\f[R] without needing a
password, but must enter her password for a \f[B]bash\f[R] running as
root:
.IP
.nf
\f[C]
[mandy_du]
name = mandy
rule = \[ha](/usr)?/bin/du .*$
require_pass = false
[mandy_some]
name = mandy
rule = \[ha](/usr)?/bin/bash$
require_pass = true
\f[R]
.fi
.PP
The rule \f[B]regex\f[R] can include repetitions.
To permit running \f[B]wc\f[R] to count the lines in the log files (we
don\[cq]t know how many there are) in \f[B]/var/log\f[R].
This sort of regex will allow multiple instances of a \f[B]()\f[R] group
with \f[B]+\f[R], which is used to define the character class
\f[B][a-zA-Z0-9-]+\f[R], the numeric class \f[B]\f[R] and the group near
the end of the line.
In other words, multiple instances of files in \f[B]/var/log\f[R] that
may end in common log rotate forms \f[B]-YYYYMMDD\f[R] or \f[B].N\f[R].
.PP
This will permit commands such as the following, note how for efficiency
find will combine arguments with \f[B]+\f[R] into fewer invocations.
\f[B]xargs\f[R] could have been used in place of \f[B]find\f[R].
.IP
.nf
\f[C]
$ find /var/log -type f -exec please /usr/bin/wc {} \[rs]+
\f[R]
.fi
.PP
Here is a sample for the above scenario:
.IP
.nf
\f[C]
[user_jim_root_wc]
name = jim
target = root
permit = true
rule = \[ha]/usr/bin/wc (/var/log/[a-zA-Z0-9-]+(\[rs].\[rs]d+)?(\[rs]s)?)+$
\f[R]
.fi
.PP
User jim may only start or stop a docker container:
.IP
.nf
\f[C]
[user_jim_root_docker]
name = jim
target = root
permit = true
rule = \[ha]/usr/bin/docker (start|stop) \[rs]S+
\f[R]
.fi
.PP
User ben may only edit \f[B]/etc/fstab\f[R], and afterwards check the
fstab file:
.IP
.nf
\f[C]
[ben_fstab]
name = ben
target = root
permit = true
type = edit
editmode = 644
rule = \[ha]/etc/fstab$
exitcmd = /bin/findmnt --verify --tab-file %{NEW}
\f[R]
.fi
.PP
User ben may list only users \f[B]eng\f[R], \f[B]net\f[R] and
\f[B]dba\f[R]:
.IP
.nf
\f[C]
[ben_ops]
name = ben
permit = true
type = list
target = \[ha](eng|net|dba)ops$
\f[R]
.fi
.PP
All users may list their own permissions.
You may or may not wish to do this if you consider permitting a view of
the rules to be a security risk.
.IP
.nf
\f[C]
[list_own]
name = \[ha]%{USER}$
permit = true
type = list
target = \[ha]%{USER}$
\f[R]
.fi
.SH DEFAULT SECTION
.PP
Sections that are named starting with \f[B]default\f[R] retain their
actions, which can be useful for turning off \f[B]syslog\f[R] or setting
a \f[B]token_timeout\f[R] globally, for example, but they will retain
\f[B]permit\f[R] which implicitly is \f[B]true\f[R], it is therefore
sensible to negate this (setting \f[B]permit=false\f[R]) and set
\f[B]permit=true\f[R] in subsequent sections as needed.
.IP
.nf
\f[C]
[default:nosyslog]
name = .*
rule = .*
require_pass = false
syslog = false
permit = false
token_timeout = 1800
[mailusers]
name = mailadm
group = true
rule = \[ha]/usr/sbin/postcat$
require_pass = true
permit = true
\f[R]
.fi
.SH EXITCMD
.PP
When the user completes their edit, and the editor exits cleanly, if
\f[B]exitcmd\f[R] is included then this program will run as the target
user.
If the program also exits cleanly then the temporary edit will be copied
to the destination.
.PP
\f[B]%{OLD}\f[R] and \f[B]%{NEW}\f[R] will expand to the old (existing
source) file and edit candidate, respectively.
To verify a file edit, \f[B]ben\f[R]\[cq]s entry to check
\f[B]/etc/hosts\f[R] after clean exit could look like this:
.IP
.nf
\f[C]
[ben_ops]
name = ben
permit = true
type = edit
editmode = 644
rule = \[ha]/etc/hosts$
exitcmd = /usr/local/bin/check_hosts %{OLD} %{NEW}
\f[R]
.fi
.PP
\f[B]/usr/local/bin/check_hosts\f[R] takes two arguments, the original
file as the first argument and the modify candidate as the second
argument.
If \f[B]check_hosts\f[R] terminates zero, then the edit is considered
clean and the original file is replaced with the candidate.
Otherwise the edit file is not copied and is left, \f[B]pleaseedit\f[R]
will exit with the return value from \f[B]check_hosts\f[R].
.PP
A common \f[B]exitcmd\f[R] is to check the validity of
\f[B]please.ini\f[R], shown below.
This permits members of the \f[B]admin\f[R] group to edit
\f[B]/etc/please.ini\f[R] if they provide a reason (\f[B]-r\f[R]).
Upon clean exit from the editor the tmp file will be syntax checked.
.IP
.nf
\f[C]
[please_ini]
name = admins
group = true
reason = true
rule = /etc/please.ini
type = edit
editmode = 600
exitcmd = /usr/bin/please -c %{NEW}
\f[R]
.fi
.SH DATED RANGES
.PP
For large environments it is not unusual for a third party to require
access during a short time frame for debugging.
To accommodate this there are the \f[B]notbefore\f[R] and
\f[B]notafter\f[R] time brackets.
These can be either \f[B]YYYYmmdd\f[R] or \f[B]YYYYmmddHHMMSS\f[R].
.PP
The whole day is considered when using the shorter date form of
\f[B]YYYYmmdd\f[R].
.PP
Many enterprises may wish to permit periods of access to a user for a
limited time only, even if that individual is considered to have a
permanent role.
.PP
User joker can do what they want as root on 1st April 2021:
.IP
.nf
\f[C]
[joker_april_first]
name = joker
target = root
permit = true
notbefore = 20210401
notafter = 20210401
rule = \[ha]/bin/bash
\f[R]
.fi
.SH DATEMATCHES
.PP
\f[B]datematch\f[R] matches against the date string \f[B]Day dd mon
HH:MM:SS UTC Year\f[R].
This enables calendar style date matches.
.PP
Note that the day of the month (\f[B]dd\f[R]) will be padded with spaces
if less than two characters wide.
.PP
You can permit a group of users to run
\f[B]/usr/local/housekeeping/\f[R] scripts every Monday:
.IP
.nf
\f[C]
[l2_housekeeping]
name = l2users
group = true
target = root
permit = true
rule = /usr/local/housekeeping/tidy_(logs|images|mail)
datematch = \[ha]Mon\[rs]s+.*
\f[R]
.fi
.SH REASONS
.PP
When \f[B]reason=true\f[R], a user must pass a reason with the
\f[B]-r\f[R] option to \f[B]please\f[R] and \f[B]pleaseedit\f[R].
Some organisations may prefer a reason to be logged when a command is
executed.
This can be helpful for some situations where something such as
\f[B]mkfs\f[R] or \f[B]useradd\f[R] might be preferable to be logged
against a ticket.
.IP
.nf
\f[C]
[l2_user_admin]
name = l2users
group = true
target = root
permit = true
reason = true
rule = \[ha]/usr/sbin/useradd -m \[rs]w+$
\f[R]
.fi
.PP
Or, if tickets have a known prefix:
.IP
.nf
\f[C]
reason = .*(bug|incident|ticket|change)\[rs]d+.*
\f[R]
.fi
.PP
Perhaps you want to add a mini molly-guard where the hostname must
appear in the reason:
.IP
.nf
\f[C]
[user_poweroff]
name = l2users
group = true
rule = (/usr)?/s?bin/(shutdown( -h now)?|poweroff|reboot)
require_pass = true
reason = .*%{HOSTNAME}.*
\f[R]
.fi
.SH DIR
.PP
In some situations you may only want a command to run within a set of
directories.
The directory is specified with the \f[B]-d\f[R] argument to
\f[B]please\f[R].
For example, a program may output to the current working directory,
which may only be desirable in certain locations.
.IP
.nf
\f[C]
[eng_build_aliases]
name = l2users
group = true
dir = \[ha]/etc/mail$
rule = \[ha]/usr/local/bin/build_aliases$
\f[R]
.fi
.SH LAST
.PP
\f[B]last = true\f[R] stops processing at a match:
.IP
.nf
\f[C]
[mkfs]
name = l2users
group = true
target = root
permit = true
reason = true
rule = \[ha]/sbin/mkfs.(ext[234]|xfs) /dev/sd[bcdefg]\[rs]d?$
last = true
\f[R]
.fi
.PP
For simplicity, there is no need to process other configured rules if
certain that the \f[B]l2users\f[R] group are safe to execute this.
\f[B]last\f[R] should only be used in situations where there will never
be something that could contradict the match in an undesired way later.
.SH SYSLOG
.PP
By default entries are logged to syslog.
If you do not wish an entry to be logged then specify
\f[B]syslog=false\f[R].
In this case \f[B]jim\f[R] can run anything in \f[B]/usr/bin/\f[R] as
root and it will not be logged.
.IP
.nf
\f[C]
[maverick]
syslog = false
name = jim
rule = /usr/bin/.*
reason = false
\f[R]
.fi
.SH FILES
.PP
/etc/please.ini
.SH NOTES
.PP
At a later date repeated properties within the same section may be
treated as a match list.
.SH CONTRIBUTIONS
.PP
I welcome pull requests with open arms.
New features always considered.
.SH BUGS
.PP
Found a bug?
Please either open a ticket or send a pull request/patch.
.SH SEE ALSO
.PP
\f[B]please\f[R](1)
.SH AUTHORS
Ed Neville (ed-please\[at]s5h.net).