added manual pages

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

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 <alemauri001@tuta.io>
 

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 <alemauri001@tuta.io>