.\" $Id: sheval.man,v 1.8 2012/09/07 15:07:22 ksb Exp $
.\" by Kevin Braunsdorf
.\" $Compile: Display%h
.\" $Display: ${groff:-groff} -Tascii -man %f | ${PAGER:-less}
.\" $Display(*): ${groff:-groff} -T%s -man %f
.\" $Install: %b -mDeinstall %o %f && cp %f $DESTDIR/usr/local/man/man7/sheval.7
.\" $Deinstall: ${rm-rm} -f $DESTDIR/usr/local/man/[cm]a[nt]7/sheval.7*
.TH SHEVAL 7 LOCAL
.SH NAME
sheval - helmet to assign dynamic values in an escalated environment

.SH SYNOPSIS
.ds PN "sheval
\fI\*(PN\fP [\fB\-P\fP\~\fIpid\fP] [\fB\-C\fP\~config] [\fB\-f\fP\~\fIfile\fP] [\fB\-g\fP\~\fIgroup\fP] [\fB\-R\fP\~\fIroot\fP] [\fB\-u\fP\~\fIuser\fP] \fImnemonic\fP \fIprogram\fP \fIeuid\fP:\fIegid\fP \fIcred_type\fP:\fIcred\fP
.br
\fI\*(PN\fP \fB\-h\fP|\fB\-H\fP
.br
\fI\*(PN\fP \fB\-V\fP

.SH DESCRIPTION
This helmet is intended to allow \fBop\fP(1) escalation rules to
include dynamic variable assignments in the escalated environment.
It does this by assigning the output from a shell command to the
specified variable, to compensates for \fBop\fP's inability to
do that.
The escalation fails when any of these commands \fBexit\fP(3)s non-zero.

.SH OPTIONS
This program takes all the \fBop\fP provided options, but actually
doesn't look at any of them (other than \fB\-P\fP).
It does sanity check them, just the same.

.SH ENVIRONMENT
Like any helmet, most of the configuration is passed from \fBop\fP
via the environment.
.TP
.nf
\fBSHEVAL_SET_\fP\fIenv\fP=\fIcmd\fP
.fi
The helmet executes the given \fIcmd\fP reading the output to
form a new value for the \fIenv\fP specified.  The last newline is
deleted from the new value.  When any \fIcmd\fP exits non-zero the
escalation is denied.  When \fIenv\fP is the empty string it is
replaced with a single under-bar (\fB_\fP).
If the \fIcmd\fP is empty, it is replaced with \fBhostname\fP.
.TP
.nf
\fBSHEVAL_WARN\fP=\fIsorry\fP
.fi
The warning message to replace the common "Sorry" denial message.
.TP
.nf
\fBSHEVAL_REVEAL\fP=\fIprefix\fP
.fi
The standard reveal logic, see \fBop-jacket\fP(7).
.TP
.nf
\fBSHEVAL_REMOVE\fP=\fIlist\fP
.fi
A comma-separated list of environment variables to remove after
processing.  This masks values that the escalated process should not
be able to see, but are required for computing other values.

.P
.hlm 0
Note that any \fIenv\fP from for the escalated environment
may have the "SHEVAL_SET_" prefix, in which case it is processed
again, at the end of the cycle.  This allows order-dependent
assignments, which may otherwise be randomized, the new command
is the evaluation of the original.  This process may be repeated
as many times as the prefix remains.
.hlm 1
.P
All of these are deleted from each \fIcmd\fP's environment:
\fB$IFS\fP, \fB$CDPATH\fP, \fB$ENV\fP, \fB$BASH_ENV\fP to prevent
\fBperl\fP(1) from refusing to run any commands.  If you must have them
set, you'll have to put each in the environment with a set specification.

.SH EXAMPLES
These are example from the command-line:
.TP
.nf
/usr/local/libexec/jacket/sheval \-V
.fi
Output the version of the program.
.TP
.nf
/usr/local/libexec/jacket/sheval \-H
.fi
Output a summary of the environment expected.

.P
All of these are snips from the \fBop\fP \fIaccess.cf\fP file.
Note that you \fBmust\fP allow any referenced environment variables
into the escalated environment, and it is a really good idea to
include a \fB$PATH\fP.
.PD 0
.TP
.nf
jacket=/usr/local/libexec/jacket/sheval $SHEVAL_SET_NOW=date
.fi
Set the environment variable $NOW to the current time.
.sp
.TP
.nf
$SHEVAL_SET_TOP=stampctl$.-V|sed$.-ne$.'s/.*cache.directory:$.\e([^$.]*\)e.*/\1/p'
.fi
.TP
.nf
jacket=/usr/local/libexec/jacket/sheval
.fi
Deposit the path to the default stamp directory in \fB$TOP\fP.
Recall that the \fBop\fP markup \fB$.\fP represents a space in the
context of an environment variable, this is a bit easier to read
than \fB$\es\fP.
.sp
.TP
.nf
$SHEVAL_SET_IFS=echo$."$\et$\en$.:"
.fi
.TP
.nf
$SHEVAL_SET_SHEVAL_SET_Targ=echo$.\fImyscript\fP
.fi
.TP
.nf
jacket=/usr/local/libexec/jacket/sheval
.fi
Restore \fB$IFS\fP to a whacky value (by including a colon), then
run \fImyscript\fP to set the value of \fB$Targ\fP.  The \fBecho\fP
command outputs a script name, the next pass executes that script.
.sp
.TP
.nf
jacket=/usr/local/libexec/jacket/sheval $SHEVAL_SET_FROM=
.fi
Set \fB$FROM\fP to the local hostname.  This is a strange default, but it is
useful in calls to the master source tools, viz. \fBhxmd\fP, \fBefmd\fP,
\fBmsrc\fP and \fBmmsrc\fP(8).
.\" Trust me,  sshw and gtfw makes this even better.
.PD

.SH BUGS
This jacket trusts that the \fBop\fP configuration won't allow a
malicious shell command through the environment filter.  The
multiple evaluation feature makes that much harder to believe.
Any configuration that calls a helmet or jacket requires great
care, but great power always comes with great responsibility.
.\" thanks Spiderman
.P
Reveals do not take place in the helmet, they may conflict
with assignments made in \fI\*(PN\fP, in which case the assignments
made from \fI\*(PN\fP overwrite the revealed values.  Revealed
variables are not visible to the \fIcmd\fP processes (but they are
still visible with the original prefix).
This means revealing \fB$IFS\fP doesn't impact any evaluations.
One should not depend on
this behavior, since it is implementation dependent (and might change).

.SH AUTHOR
K S Braunsdorf, from the Non-Player Character Guild
.br
op at-not-a-spammer ksb dot npcguild.org

.SH "SEE ALSO"
.hlm 0
sh(1), op(1l), op-jacket(7l), stampctl(8l), getpeereid(3), hostname(1),
msrc(8l)