From e2284c301b07dabbf2e704f026eac1ed4314960d Mon Sep 17 00:00:00 2001 From: Alessandro Mauri Date: Thu, 15 Jul 2021 23:18:46 +0200 Subject: [PATCH] added manual pages --- makefile | 14 +++++--- us.1 | 78 +++++++++++++++++++++++++++++++++++++++++++- us.conf.5 | 97 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 183 insertions(+), 6 deletions(-) create mode 100644 us.conf.5 diff --git a/makefile b/makefile index ec44415..8846b2a 100644 --- a/makefile +++ b/makefile @@ -18,13 +18,17 @@ install: us cp -f us ${DESTDIR}${PREFIX}/bin/us chown 0:0 ${DESTDIR}${PREFIX}/bin/us chmod 4755 ${DESTDIR}${PREFIX}/bin/us -# mkdir -p ${DESTDIR}${MANPREFIX}/man1 -# cp -f us.1 ${DESTDIR}${MANPREFIX}/man1/us.1 -# chmod 644 ${DESTDIR}${MANPREFIX}/man1/us.1 + mkdir -p ${DESTDIR}${MANPREFIX}/man1 + cp -f us.1 ${DESTDIR}${MANPREFIX}/man1/us.1 + chmod 644 ${DESTDIR}${MANPREFIX}/man1/us.1 + mkdir -p ${DESTDIR}${MANPREFIX}/man5 + cp -f us.conf.5 ${DESTDIR}${MANPREFIX}/man5/us.conf.5 + chmod 644 ${DESTDIR}${MANPREFIX}/man5/us.conf.5 uninstall: - rm -f ${DESTDIR}${PREFIX}/bin/us -# ${DESTDIR}${MANPREFIX}/man1/us.1 + rm -f ${DESTDIR}${PREFIX}/bin/us \ + ${DESTDIR}${MANPREFIX}/man1/us.1 + ${DESTDIR}${MANPREFIX}/man1/us.conf.5 clean: rm -f us us-dbg diff --git a/us.1 b/us.1 index 443c80e..7cc14d2 100644 --- a/us.1 +++ b/us.1 @@ -1,2 +1,78 @@ -US-0.1 +.TH US 1 "JULY 2021" "Alessandro Mauri" + +.SH NAME +us \- execute command with another identity + +.SH SYNOPSIS +.SY us +.OP \-hseA +.OP \-u user +.OP \-g group +.OP \-C config +.OP command +.OP args +.YS + +.SH DESCRIPTION +.PP +The +.BR us +utility executes the given command as another identity, which by default is +root. If no command is specified, it starts a shell as that user. +.PP +In order to execute anything users need to authenticate and the user + target +identity configuration must be allowed in the configuration file, see +.BR us.conf(5) +for more information. +.PP +By default when a command or shell gets executed a new environment gets created, +USER is set with the target user, as well as LOGNAME, SHELL and HOME get all set +with the default values for the target user. +PATH, TERM, EDITOR, VISUAL, DISPLAY and XAUTHORITY instead are kept between +execution. +Lastly a new variable US_USER is added (but not overridden) which contains the +calling user's username. +.PP +Invoking the program logs by default to +.BR syslog(2) +the outcome of the invocation, this behaviour can be changed in the config. + +.SH OPTIONS +.IP \-h +Print usage info message. +.IP \-s +Use the calling user's SHELL instead of the target user's one. +.IP \-e +Keep the entire environment between execution instead of just PATH, TERM, +EDITOR, VISUAL, DISPLAY and XAUTHORITY; user variables still get overridden. +.IP \-A +Instead of prompting for a password, +.BR us +executes the command specified in the variable US_ASKPASS and reads it's stdout +as the password. If US_ASKPASS is not specified then it will fall back +prompting the password. +.IP "\-u user" +Change the target identity to +.I user +(default is root). +.IP "\-g group" +Set the group of the target user to +.I group +instead of the target user's default, also add it to the group list. +.IP "\-C config" +Use the specified config file + +.SH "RETURN VALUE" +The +.BR us +utility returns 0 on success and != 0 on failure which may occur on +various occasions, along with an error a message will be outputted to specify +the reason. + +.SH "SEE ALSO" +.BR su(1) +.BR us.conf(5) + +.SH AUTHOR +Alessandro Mauri diff --git a/us.conf.5 b/us.conf.5 new file mode 100644 index 0000000..79e856d --- /dev/null +++ b/us.conf.5 @@ -0,0 +1,97 @@ +.TH US.CONF 5 "JULY 2021" "Alessandro Mauri" + +.SH NAME +us.conf \- us configuration file + +.SH DESCRIPTION +.PP +The +.BR us(1) +utility executes commands as another identity according to the rules in the +.BR us.conf +configuration file. +.PP +The rules have the following format: +.IP +.BR "+|\-" +.BR user +as +.BR target +.OP options +.OP ENV +.SS Options +Possible options are: +.IP nopass +The user is not required to enter a password. +.IP persist +Once entering the password for the first time, a timer for five minutes is +started, during those five minutes the user is not required to re-enter +the password for that session. Re-invoking us resets that timer. +.IP nolog +Do not log to +.BR syslog(2) +command outcome +.PP +The sum of matching rules determines the action taken, if no rules match +the action is denied. +.PP +Comments are made by having the first non-blank character of a line be an hash +mark ('#'), comments take up the whole line and cannot be embedded in the +middle of a line. +.PP +A valid user or target is an alphanumeric string containing the name of the +target. If the target is a user, the string begins with [0-9A-z]; if the +target is a group then the has to begin with ':'. Instead of the name of the +user/group it's number can be used, in that case the part of the string that +would contain the name must begin with '#' (so after a possible ':'). +.PP +As options a comma separated list of environment variables can be specified, +these will be added or will override existing environment variables during +execution of the command. A valid environment variable list starts with an +uppercase letter and ends at the next space. +.PP +A valid config line must be owned by root:root and should not be readable, +writeable or executable for any other user or group, if the config file fails +to meet this requirements it will get rejected and invocation will fail. + +.SH FILES +.IP /etc/us.conf +us(1) configuration file + +.SH EXAMPLES +.PP +The following example will allow root to execute commands as itself without +requiring a password and without logging: +.PP +.EX ++ root as root nopass nolog +.EE +.PP +This next example allows users in the wheel group to execute commands as +root including a new environment variable IS_WHEEL set to 'yes' and the variable +EDITOR will be set to ed, the standard unix editor: +.PP +.EX ++ :wheel as root IS_WHEEL=yes,EDITOR=ed +.EE +.PP +In this example the user maria is allowed to execute commands as a member of +the group wheel and the session is remembered so that in the next five +minutes the password won't be needed: +.PP +.EX ++ maria as :wheel persist +.EE +.PP +This time the user joe is denied to execute commands as anyone who's member of +the group 'coolppl' because joe is uncool +.PP +.EX +- joe as :coolppl +.EE + +.SH "SEE ALSO" +.BR us(1) + +.SH AUTHOR +Alessandro Mauri