wrapw - consolidate wrapped environment to a single diversion socket
wrapw [-IQW] [-depth] [-t wrap] [client]
wrapw [-W] [-depth] [-t wrap] -R [record]
wrapw -m [-dE] [-N path] [utility]
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 sshw(1l) to create a proxy environment to
forward to the remote host.
By default wrapw doesn't proxy instances of itself. Specify -E to
force ancestral encapsulation.
In client mode wrapw 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 -t) that name
replaces the socket name throughout the restored diversion stack. This
allows a proxy service (like sshw) to forward clients as they connect.
Note that any such service must forward SCM messages, see recvmsg(2),
including rights, credentials and timestamps for any wrappers to work.
This command reads the environment variable WRAPW for options. If the
program is called as wrapw then no options are forced.
Select an outer diversion, depth steps away. Client wrapw
instances may attach to outer diversions with this option. This
option may only be given once.
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 vari-
able wrapw_d contains the path to the new diversion socket, in
Include every instance of wrapw in the encapsulated stack.
Print only a brief help message.
Integrate the new wrappers into the existing wrapper stack.
This pushes the wrappers provided by wrap into the existing
stack. If you have 2 instances of "tiger" and we added 1 then
the lone instance is renumbered from tiger_1 to $tiger_3 and the
new depth is set as $tiger_link=3. Thus the newly added
instance is the top of stack, and the others enclose it. With-
out this option the 2 existing diversions would be unavailable
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 wrapw itself
include the -E option.
Force a UNIX domain name for this service.
Tell the enclosing persistent instance to finish.
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 wrapw. It is also not useful beyond the
life of the running stack-context.
The record specification may be "-" to output to stdout. The
receiving instance of wrapw replaces stdin with either /dev/tty
or /dev/null, on a first available basis.
Source for a client's wrapped environment. Specify the path to
a UNIX domain socket. This option is used, for example, by
The wrap may also be a record file (created under -R), or the
special file dash ("-") which reads stdin, which may be a file
or a connected local domain socket.
Show only the standerd version banner for a wrapper.
Include the whole environment in the request for the diversion
stack. This is not a great way to operate and is not recom-
mended because some state in the environment is not really sane
to pass between sessions.
The -Z option is no longer supported, replace it with "-t/dev/null".
The manager process (under -m) accepts connections on the new diversion
socket. A rule was made explicitly for wrapw 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.
After the initial connection clients immediately present a small inte-
ger, which is encoded on the end of the diversion environment socket
variable, that integer tells wrapw which of the enclosed diversions it
The clients know to do this because the base code for a wrapper diver-
sion 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.
At this point wrapw can send new rights to the client, or proxy the
connection itself. The code in the client library allows either tac-
tic. See the mkcmd(1l) module "util_divconnect" for the code.
A manager instance started with the special command ":" is persistent,
as ptbw(1l) or xclate(1l) would be. Any client that specified the -Q
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
connect(2) to the socket can shutdown the service (unless it is waiting
for some other process; not in "colon" mode, see forever(1)).
A manager started under -mdE 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 wrapw_d
may be used by any other program to form another isolated diversion.
Never depend on this variable being passed any deeper than directly
from wrapw to utility.
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 msrc(8l) or hxmd(8l)
may create xclate or ptbw instances between manager instance and the
clients that are indirectly created.
Clients may connect to the wrapw diversion socket to access a shell
client 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.
Clients of detached managers must specify the path to the diversion
socket under -t. The path wrap requires is often recorded in a self-
managed environment variable, or a file managed by the application that
requires the diversion.
Clients that have no direct access to the process tree that started the
wrappers may still connect by means of a file. Create a record file
with the -R option, send the name (or contents) to any unrelated pro-
cess. A client instance may import the environment under -t. Then,
assuming that the common diversion socket's modes allow the client to
connect(1), any descendant processes have access to that whole diver-
The op(1l) jacket wrope(7l) provides a service based on an instance of
Output the standard version information and list open diver-
wrapw -m wrapw -V
Same a above, but force at least one open diversion.
ptbw -m -R1 wrapw -m ptbw -m -R5 wrapw ptbw
Shows a ptbw tableau of 1 token, since the wrapw restores access
to the stack as it was in the scope of the first instance of
ptbw -m -R1 wrapw -m ptbw -m -R5 wrapw -m ptbw
The last instance of wrapw is now a manager, so this outputs the
ptbw tableau with 5 tokens, since that is the top of the diver-
ptbw -m -R1 wrapw -t /dev/null ptbw -V
Start a ptbw diversion, only hide it with a wrapw client that
reads an empty file for the diversion stack. Thus ptbw reports
"ptbw: no current diversions".
ptbw -t /tmp/tokens -m wrapw -m -N /tmp/known :
Start a ptbw running with a persistent wrapw to hold it open.
ptbw -t /tmp/tokens -m wrapw -m -N /tmp/known forever awake
An alternate expression of the ptbw instance as above, but
clients may not end it with a quit (-Q) request. Someone must
shoot the forever(1l) instance, usually with pkill(1).
wrapw -t /tmp/known -R $SHARED
Create a record of the diversion stack containing the ptbw in
wrapw -t $SHARED ptbw -A echo Using token:
Fetch a token from the encapsulated ptbw.
wrapw -t $SHARED -Q date +"Ended on %c"
Tell the persistent instance to quit. Note that this has no
effect on the alternate example instance started with for-
pkill -TERM -fu nobody "^forever [a]wake"
Safely terminate the forever instance above, assuming it was run
None known. The chat protocol used between manager and client
instances is not documented because I will change in the next major
The -W mode passes values across sessions/hosts that break programs
(like X clients, screen(1) sessions, and ssh-agent(1) sessions). Take
care to filter the new environment before starting any processing.
NonPlayer Character Guild
wrapw swirl ksb.npcguild dot negative-spam org
sshw(1l), xapply(1l), sh(1), ptbw(1l), xclate(1l), hxmd(8l), msrc(8l),
wrope(7l), forever(1l), pkill(1)