WRAPW(1)                                                              WRAPW(1)



NAME
       wrapw - consolidate wrapped environment to a single diversion socket

SYNOPSIS
       wrapw [-IQW] [-depth] [-t wrap] [client]
       wrapw [-W] [-depth] [-t wrap] -R [record]
       wrapw -h
       wrapw -V
       wrapw -m [-dE] [-N path] [utility]

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 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.

OPTIONS
       This  command reads the environment variable WRAPW for options.  If the
       program is called as wrapw then no options are forced.

       -depth
              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.

       -d
              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
              utility's environment.

       -E
              Include every instance of wrapw in the encapsulated stack.

       -h
              Print only a brief help message.

       -I
              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
              from client.

       -m
              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.

       -N path
              Force a UNIX domain name for this service.

       -Q
              Tell the enclosing persistent instance to finish.

       -R [record]
              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.

       -t wrap
              Source  for a client's wrapped environment.  Specify the path to
              a UNIX domain socket.  This option  is  used,  for  example,  by
              sshw.

              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.

       -V
              Show only the standerd version banner for a wrapper.

       -W
              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".

MANAGER
       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
       should select.

       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.

CLIENT
       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-
       sion stack.

       The  op(1l) jacket wrope(7l) provides a service based on an instance of
       wrapw.

EXAMPLES
       wrapw -V
              Output the standard version information  and  list  open  diver-
              sions.

       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.

       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-
              sion stack.

       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
              $SHARED.

       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-
              ever(1l), above.

       pkill -TERM -fu nobody "^forever [a]wake"
              Safely terminate the forever instance above, assuming it was run
              as nobody.

BUGS
       None  known.   The  chat  protocol  used  between  manager  and  client
       instances is not documented because I will change  in  the  next  major
       release.

       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.

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

SEE ALSO
       sshw(1l),  xapply(1l), sh(1), ptbw(1l), xclate(1l), hxmd(8l), msrc(8l),
       wrope(7l), forever(1l), pkill(1)



                                     LOCAL                            WRAPW(1)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | MANAGER | CLIENT | EXAMPLES | BUGS | AUTHOR | SEE ALSO