.\" $Id: wrope.man,v 1.4 2012/02/24 20:47:46 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/wrope.7
.\" $Deinstall: ${rm-rm} -f $DESTDIR/usr/local/man/[cm]a[nt]7/wrope.7*
.TH WROPE 7 LOCAL
.SH NAME
wrope - extend a wrapped environment to an op escalated process

.SH SYNOPSIS
.ds PN "wrope
\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 access from an escalated shell to the client's
wrapper diversions.
It does this creating a \fBwrapw\fP(1) diversion that multiplexes
the existing diversion stack under a single domain socket, then
\fBchown\fPs that socket to the escalated login (and group).
.P
The escalated process is provided with the diversion tableau from
the new instance of \fBwrapw\fP.  Since the \fBwrapw\fP process runs as
the client login, in a different session, is it unlikely that
the escalated login can suborn it.
.P
Since this program must manage the running diversion process as well
as the escalated process, it must be specified as a jacket
(rather than a helmet).

.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 jacket, most of the configuration is passed from \fBop\fP
via the environment.
.TP
.nf
\fBWROPE_TO\fP=\fItemplate\fP
.fi
A template to generate (with \fBmkdtemp\fP(3) and \fBmktemp\fP(3)) a
unique location for the new diversion socket.  The default is
\*(lq/tmp/wropeXXXXXX/wp0\*(rq.  That mocks the location \fBwrapw\fP
would use enough that new diversions that nest under \fBwrapw\fP will
still work.
.TP
.nf
\fBWROPE_REVEAL\fP=\fIprefix\fP
.fi
The standard reveal logic, see \fBop-jacket\fP(7).

.P
All of these are deleted from each \fBwrapw\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.  There is no way in
the jacket to set them for \fBwrapw\fP.
.P
Ancestrial instance of \fBwrapw\fP may know the value of other environment
variables, e.g. those not provided to the escalated environment.
For example, the original $PATH might be recovered with:
.RS
.nf
wrapw \-1 \-WR \- |tr '\e000' '\en' |grep "^PATH="
.fi
.RE
This does depend on an existing \fBwrapw\fP diversion in-play before
\fBop\fP was executed, which usually means you coded a script to
make that happen.

.SH EXAMPLES
These are example from the command-line:
.TP
.nf
/usr/local/libexec/jacket/wrope \-V
.fi
Output the version of the program.
.TP
.nf
/usr/local/libexec/jacket/wrope \-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/wrope
.fi
.TP
.nf
environment=^.*_link$,^.*_d$,^.*_[0-9][0-9]*$
.fi
.TP
.nf
$TERM $TERMCAP $PERP=$l
.fi
This is the most common spell to run this jacket.  It allows all
well-formed wrapper varaibles to be passed to the jacket, which
replaces them with the mappings from \fBwrapw\fP.  This gives
the escalated process access to all in-scope diversions.
.sp
.TP
.nf
jacket=/usr/local/libexec/jacket/wrope
.fi
.TP
.nf
environment=^ptbw_,^xclate_,^gtfw_,^sshw_
.fi
.TP
.nf
$TERM $TERMCAP $PERP=$l
.fi
Allow only diversions for wrappers we know through to the escalated
process.  To cut off access to the original environment don't include
any instances of \fBwrapw\fP.

.PD
.SH BUGS
It might be possible to trick a wrapper into doing something unexpected,
but I've never had a problem with that.

.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), wrapw(1l), ptbw(1l), xclate(1l),
proxy-agent(7l), hxmd(8l)