.\" $Id: wrapw.man,v 1.20 2012/05/21 18:25:12 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/man1/wrapw.1
.\" $Deinstall: ${rm-rm} -f $DESTDIR/usr/local/man/[cm]a[nt]1/wrapw.1*
.TH WRAPW 1 LOCAL
.SH NAME
wrapw - consolidate wrapped environment to a single diversion socket
.SH SYNOPSIS
.ds PN "wrapw
\fI\*(PN\fP [\fB\-IQW\fP] [\-\fIdepth\fP] [\fB\-t\fP\~\fIwrap\fP] [\fIclient\fP]
.br
\fI\*(PN\fP [\fB\-W\fP] [\-\fIdepth\fP] [\fB\-t\fP\~\fIwrap\fP] \fB\-R\fP [\fIrecord\fP]
.br
\fI\*(PN\fP \fB\-h\fP
.br
\fI\*(PN\fP \fB\-V\fP
.br
\fI\*(PN\fP \fB\-m\fP [\fB\-dE\fP] [\fB\-N\fP\~\fIpath\fP] [\fIutility\fP]

.SH DESCRIPTION
This multiplexer consolidates every wrapper diversion in the
current environment into a single UNIX domain socket.  It rewrites
the active wrapper environment variables to reference that single
socket.  This is almost exclusively used by \fBsshw\fP to
create a proxy environment to forward to the remote host.
.P
By default \fI\*(PN\fP doesn't proxy instances of itself.  Specify
\fB\-E\fP to force ancestral encapsulation.
.P
In client mode \fI\*(PN\fP builds an environment that restores
the complete diversion stack as it was when the specified
diversion was created.  If the name of the diversion socket is
specified (under \fB\-t\fP) that name replaces the socket
name throughout the restored diversion stack.  This allows a
proxy service (like \fIsshw\fP) to forward clients as they connect.
Note that any such service \fBmust\fP forward SCM messages,
see \fBrecvmsg\fP(2), including rights, credentials and timestamps
for any wrappers to work.

.SH OPTIONS
This command reads the environment variable \fBWRAPW\fP for options.
If the program is called as \fI\*(PN\fP then no options are forced.
.TP
\fB\-\fIdepth\fP
Select an outer diversion, depth steps away.  Client \fI\*(PN\fP
instances may attach to outer diversions with this option.
This option may only be given once.
.TP
\fB\-d\fP
Use this option start managers which are detached from the linked
environment.  The isolated
diversion allows the same transparent linkage as any other wrapper.
The environment variable \fBwrapw_d\fP contains the path
to the new diversion socket, in \fIutility\fP's environment.
.TP
\fB\-E\fP
Include every instance of \fI\*(PN\fP in the encapsulated stack.
.TP
\fB\-h\fP
Print a brief help message.
.TP
\fB\-I\fP
Integrate the new wrappers into the existing wrapper stack.
This pushes the wrappers provided by \fIwrap\fP into the existing
stack.  If you have 2 instances of "tiger" and we added 1 then the
lone instance is renumbered from \fBtiger_1\fP to \fB$tiger_3\fP and
the new depth is set as \fB$tiger_link=3\fP.
Thus the newly added instance is the top of stack, and the others
enclose it.  Without this option the 2 existing diversions would be
unavailable from \fIclient\fP.
.TP
\fB\-m\fP
Manage existing diversions for descendant processes.
Start a new diversion which encapsulates all the open wrappers under
a single socket.
To encapsulate outer instances of \fI\*(PN\fP itself include
the \fB\-E\fP option.
.TP
\fB\-N\fP \fIpath\fP
Force a UNIX domain name for this service.
.TP
\fB\-Q\fP
Tell the enclosing persistent instance to finish.
.TP
\fB\-R\fP [\fIrecord\fP]
Build a list of the environment variables required to reproduce
the current wrapper stack.  This opaque file is not useful to any
program other than \fI\*(PN\fP.  It is also not useful beyond
the life of the running stack-context.
.sp
The \fIrecord\fP specification may be \*(lq-\*(rq to output to
\fIstdout\fP. The receiving instance of \fI\*(PN\fP replaces
\fIstdin\fP with either \fB/dev/tty\fP or \fB/dev/null\fP, on a
first available basis.
.TP
\fB\-t\fP \fIwrap\fP
Source for a client's wrapped environment.  Specify the path to a
UNIX domain socket.  This option is used, for example, by \fBsshw\fP.
.sp
The \fIwrap\fP may also be a \fIrecord\fP file (created under \fB\-R\fP),
or the special file dash (\*(lq\-\*(rq) which reads \fIstdin\fP, which
may be a file or a connected local domain socket.
.\" In the future it might be a directory as well --ksb
.TP
\fB\-V\fP
Show version information.
.TP
\fB\-W\fP
Include the whole environment in the request for the diversion stack.
This is not a great way to operate and is not recommended because some
state in the environment is not really sane to pass between sessions.

.SH MANAGER

.P
The manager process (under \fB\-m\fP) accepts connections on the new
diversion socket.
A rule was made explicitly for \fI\*(PN\fP in the wrapper interface
code: it allows the manager process to accept connections for
any outer diversion, then proxy the client to the correct one.

.P
After the initial connection clients immediately present a small integer,
which is encoded on the end of the diversion environment socket variable,
that integer tells \fI\*(PN\fP which of the enclosed diversions it
should select.
.P
The clients know to do this because the base code for a wrapper diversion
codes a rule to connecting to "nonexistent" sockets which forces them
to connect to the path without the last component, they send the
last component as a command to fetch a proxy to the correct diversion,
which happens to be the required integer token.
.\" Yes, I did this years before the release of the program.  See I'm clever.
.P
At this point \fI\*(PN\fP can send new rights to the client, or
proxy the connection itself.  The code in the client library
allows either tactic.
.\" Didn't see that coming, did'ya?  Well, I did.
See the \fBmkcmd\fP module \*(lqutil_divconnect\*(rq for the code.

.P
A manager instance started with the special command \*(lq\fB:\fP\*(rq is
persistent, as \fBptbw\fP or \fBxclate\fP would be.  Any client
that specified the \fB\-Q\fP option will terminate the
persistent instance when it disconnects.  This is generally
useful to allow boot-time global services to bind to locally
known local domain sockets.  Be aware that any client that can
\fBconnect\fP(2) to the socket can \fBshutdown the service\fP (unless it is
waiting for some other process; not in \*(lqcolon\*(rq mode).

.P
A manager started under \fB\-mdE\fP is used to hold the state
of the whole diversion stack via a single path.
The name of the diversion socket should be passed out-of-band to
any clients, as the variable \fBwrapw_d\fP may be used by any
other program to form another isolated diversion.  Never depend
on this variable being passed any deeper than directly from
\fI\*(PN\fP to \fIutility\fP.
.P
A detached diversion allows an indirect process to access the
same stack as was in-play when that diversion was created.  This
may allow clients to access wrappers which would otherwise be
an unknown stack depth away.  For example recursive instances
of \fBmsrc\fP or  \fBhxmd\fP may create \fBxclate\fP or \fBptbw\fP
instances between manager instance and the clients that are
indirectly created.

.SH CLIENT
Clients may connect to the \fI\*(PN\fP diversion socket to
access a shell \fIclient\fP with wrapper stack as it was when the diversion
was created.  This masking of the intervening stack is
used to connect to an outer instance of any wrapper without knowing
how many levels have been pushed in the interim.

.P
Clients of detached managers must specify the path to the
diversion socket under \fB\-t\fP.  The path \fIwrap\fP requires is
often recorded in a self-managed environment variable, or a file managed
by the application that requires the diversion.
.P
Clients that have no direct access to the process tree that started
the wrappers my still connect by means of a file.  Create a \fIrecord\fP file
with the \fB\-R\fP option, send the name (or contents) to any unrelated
process.  A client instance may import the environment under \fB\-t\fP.
Then, assuming that the common diversion socket's modes allow the
client to \fBconnect\fP(1), any descendant processes have access to
that whole diversion stack.
.P
The \fBop\fP(1l) jacket \fBwrope\fP(7l) provides a service based
on an instance of \fI\*(PN\fP.

.SH EXAMPLES
.TP
.nf
\fI\*(PN\fP \-V
.fi
Output the standard version information and list open diversions.
.TP
.nf
\fI\*(PN\fP \-m \fI\*(PN\fP \-V
.fi
Same a above, but force at least one open diversion.
.TP
.nf
ptbw \-m \-R1 \fI\*(PN\fP \-m ptbw \-m \-R5 \fI\*(PN\fP ptbw
.fi
Shows a \fBptbw\fP tableau of 1 token, since the \fI\*(PN\fP
restores access to the stack as it was in the scope of the first
instance of \fBptbw\fP.
.TP
.nf
ptbw \-m \-R1 \fI\*(PN\fP \-m ptbw \-m \-R5 \fI\*(PN\fP \-m ptbw
.nf
The last instance of \fI\*(PN\fP is now a manager, so this
outputs the \fBptbw\fP tableau with 5 tokens, since that is
the top of the diversion stack.
.TP
.nf
ptbw \-m \-R1 \fI\*(PN\fP \-t /dev/null ptbw \-V
.fi
Start a \fBptbw\fP diversion, only hide it with a \fI\*(PN\fP client
that reads an empty file for the diversion stack.  Thus \fBptbw\fP
reports \*(lqptbw: no current diversions\*(rq.
.TP
.nf
ptbw \-t /tmp/tokens \-m \fI\*(PN\fP \-m \-N /tmp/known :
.fi
Start a \fBptbw\fP running with a persistent \fI\*(PN\fP to
hold it open.
.TP
.nf
\fI\*(PN\fP \-t /tmp/known \-R $SHARED
.fi
Create a record of the diversion stack containing the \fBptbw\fP in
\fI$SHARED\fP.
.TP
.nf
\fI\*(PN\fP \-t $SHARED  ptbw \-A echo Using token:
.fi
Fetch a token from the encapsulated \fBptbw\fP.
.TP
.nf
\fI\*(PN\fP \-t $SHARED \-Q date +"Ended on %c"
.fi
Tell the persistent instance to quit.

.SH BUGS
None known.  The chat protocol used between manager and client
instances is not documented because I will change in the next
major release.
.PP
The \fB\-W\fP mode passes values across sessions/hosts that break
programs (like X clients, screen sessions, and \fBssh-agent\fP
sessions).  Don't use it without great care.
.\".P
.\"The \fB\-Z\fP option was replaced with \*(lq-t /dev/null\*(rq.

.SH AUTHOR
KS Braunsdorf
.br
NonPlayer Character Guild
.br
wrapw swirl ksb.npcguild dot negative-spam org

.SH "SEE ALSO"
.hlm 0
sshw(1l), xapply(1l), sh(1), ptbw(1l), xclate(1l), hxmd(8l), msrc(8l),
wrope(7l)