.\" $Id: coat.man,v 1.4 2012/02/29 18:45:36 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/coat.7
.\" $Deinstall: ${rm-rm} -f $DESTDIR/usr/local/man/[cm]a[nt]7/coat.7*
.TH COAT 7 LOCAL
.SH NAME
coat - apply multiple jackets to an escalation
.SH SYNOPSIS
.ds PN "coat
\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 jacket allows multiple jackets (or helmets) to be applied to a
single escalation.
It does this by creating a synthetic environment for each jacket that
makes it look like it is talking directly to \fBop\fP(1).
It creates shim processes to \fBexit\fP with the correct \fIstatus\fP
under each jacket process.  It passes the external commands issued from
each jacket to \fBop\fP and acts on each environment assignment
and reveal logic as best it can.  This is not a perfect emulation,
but it works in all real-world cases.
.P
The program may be specified as a jacket or helmet.  The jacket case
is much more common.
.P
It is uncommon, but not unknown, to use this to weld together multiple
\fBstamp\fP instances to authorize a critical escalation.

.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 pass them on to each jacket instance it creates: each of
these may check the options.
In the jacket case it also updates the \fB\-P\fP option for each
new instance.

.SH ENVIRONMENT
Like any jacket, most of the configuration is passed from \fBop\fP
via the environment.
.TP
.nf
\fBCOAT\fP=\fIjackets\fP
.fi
Usually the first \fIjacket\fP in the colon (\fB:\fP) separated
list is an absolute path, any other \fIjackets\fP are taken from
the same directory as the last full path.  If the name of the program
is given as an absolute path, then that directory is the default.
Each \fIjacket\fP is layered, and must complete its external input
stream on \fIstdout\fP, before the next is applied.
.TP
.nf
\fBCOAT_REVEAL\fP=\fIprefix\fP
.fi
The standard reveal logic, see \fBop-jacket\fP(7).
This would allow one level of \fI\*(PN]\fP to enable another,
that might be poor form, as it shouldn't ever really be required.
.P
These are \fBnot\fP deleted the environment:
\fB$IFS\fP, \fB$CDPATH\fP, \fB$ENV\fP, \fB$BASH_ENV\fP, or \fB$PATH\fP
so don't allow unsafe values through the environment.

.SH EXAMPLES
These are example from the command-line:
.TP
.nf
/usr/local/libexec/jacket/coat \-V
.fi
Output the version of the program.
.TP
.nf
/usr/local/libexec/jacket/coat \-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.  (And to filter the list above well.)

.PD 0
.TP
.nf
jacket=/usr/local/libexec/jacket/coat
.fi
.TP
.nf
$COAT=wrope:proxy-agent
.fi
.TP
.nf
$WROPE_TO=/var/tmp/prxyXXXXXX/wr0.XXXXXX $TERM $TERMCAP $PERP=$l
.fi
.TP
.nf
environment=^.*_link$,^.*_d$,^.*_[0-9][0-9]*$
.fi
This is a common spell to run this jacket.  Proxy the current
wrapper environment as well as the \fBssh-agent\fP socket to
the escalated command.  See \fBwrope\fP(7) and \fBproxy-agent\fP(7).
.sp
.TP
.nf
helmet=/usr/local/libexec/jacket/coat
.fi
.TP
.nf
$COAT=/opt/tiger/libexec/jacket/puma:hunter
.fi
.TP
.nf
environment=^.*_link$,^.*_d$,^.*_[0-9][0-9]*$
.fi
It is also likely that his is cut from a sentinel configuration.
It selects 2 helmets from the tiger application's arsenal of freedom.
This forces the escalation to "and" the results of
the two checks.  There is no "or" jacket in the standard distribution.
One could be coded from the source to \fI\*(PN\fP.
.sp
.TP
.nf
jacket=/usr/local/libexec/jacket/coat
.fi
.TP
.nf
$COAT=proxy-agent:coat $L2Z_COAT=wrope
.fi
.TP
.nf
$COAT_REVEAL=L2Z_
.fi
.TP
.nf
environment=^.*_link$,^.*_d$,^.*_[0-9][0-9]*$ $TERM $TERMCAP $PERP=$l
.fi
This example shows how to spawn an instance of \fI\*(PN\fP from
itself.  We reveal the second level of configuration (the call
to \fBwrope\fP) after the first instance reads the environment, and
before the configured jackets are started.
While it is nice to know one could do that, I doubt there is a case
that really requires nested \fI\*(PN\fP's.


.PD
.SH BUGS
Signal \fIstatus\fP returns are not passed cleanly by most jackets.
The singal number is converted to an exit, which is not really cool.

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

.SH "SEE ALSO"
.hlm 0
op(1l), op-jacket(7l), proxy-agent(7l), wrope(7), stamp(7), exit(3)