[Plash] Proposed plash-exec command

[Mark Seaborn]

I'm planning to implement the command line tool described below.  The
aim is to provide a simple programmatic interface for running a
program with limited authority.  This is as an alternative to the
Plash shell.  Any comments?


NAME
       plash-exec  - Run a program, giving it less authority than
       the caller

SYNOPSIS
       plash-exec
         [--no-default]
         --prog filename
         [ -f[awls]... pathname
         | -t[awls]... pathname pathname
         | -a string
         | --cwd dir
         | --no-cwd
         | --copy-cwd ]...
         [--x11]

DESCRIPTION
       plash-exec runs programs under the Plash  environment.  It
       starts  a  process  with  a subset of the caller process's
       authority. The caller can grant the  callee  read-only  or
       read-write access to specific files and directories, which
       can be mapped at any point in the filesystem namespace.

       plash-exec  provides  a  programmatic  interface.  It   is
       intended to be used from Bash shell scripts and other pro-
       grams. Since it works via the command line, it can be used
       from  virtually  any  language,  in  contrast  to  an API.
       plash-exec is different from the Plash shell,  which  does
       not provide a programmatic interface: Plash shell commands
       are intended to be written by hand, not generated automat-
       ically.

       plash-exec  constructs  two  things  to pass to the callee
       program: a  list  of  argument  strings  (as  received  by
       main()),  and a file namespace. The -a option adds strings
       to the argument list, in order. The -f and -t options  add
       files  and directories to the file namespace. These can be
       combined: -fa and -ta add an object to the file  namespace
       and a corresponding filename to the argument list.

       plash-exec  grants  access to some directories and devices
       by default, as part of a default  installation  endowment.
       This is equivalent to the arguments:

       -fl /usr
       -fl /bin
       -fl /lib
       -fl /etc
       -fl,objrw /dev/tty
       -fl,objrw /dev/null

       This can be disabled with --no-default.

       plash-exec  can  be  used to invoke executable objects, in
       which case the callee can have access to objects that  the
       caller doesn't have access to.

OPTIONS
       For  options  that take one parameter, there are two forms
       to choose from: "--option arg"  and  "--option=arg".   The
       first  form  may  be  more  convenient  to generate in a C
       program.  The latter may be more readable in  hand-written
       shell scripts.

       --prog filename
       --prog=filename
              This  gives  the  filename  of the executable to be
              invoked. If it doesn't contain a slash, it will  be
              looked up in PATH.

              Note  that  if  the  executable  is  a "#!" script,
              access to the interpreter  specified  in  the  "#!"
              line will not be implicitly granted.

       --prog-sock filename
       --prog-sock=filename
              Invoke  an  executable  object  rather than an exe-
              cutable file. The executable object is  taken  from
              the  socket  named  by  filename.  An object can be
              exported to a socket using plash-socket-publish.

              This option implies --no-default.

       -f[awls]...[,option]... pathname
       -f[awls]...[,option]...=pathname
              Grant access to a file or directory (given by path-
              name),  and optionally add pathname to the argument
              list.  This  takes  the   following   single-letter
              options.  The multi-character options must be sepa-
              rated by commas.

              a      Add pathname to the argument  list.  Equiva-
                     lent to adding the argument "-a pathname".

              w      Grant  read/write  access to the slot speci-
                     fied by pathname. By default,  without  this
                     option,  read-only  access is granted to the
                     file or directory specified by pathname.

              l      Follow symbolic links (the "l" is for  "foL-
                     Low").  If pathname contains symbolic links,
                     these will be followed, potentially granting
                     access to the objects the links point to.

              s      Grant permission to create symbolic links.

              objrw  Grant  read/write  access  to  the  file  or
                     directory object, but not the  slot,  speci-
                     fied  by pathname. This is useful for grant-
                     ing  access  to  writable  devices  such  as
                     /dev/null.

              socket Grant  permission  to connect to Unix domain
                     sockets (as the w option does), but  without
                     granting  write access to file and directory
                     objects.

       -t[awls]...[,option]... dest-pathname source-pathname
              Grant access to a file or  directory  (source-path-
              name), but attach it to a different pathname in the
              filesystem   (dest-pathname).     Optionally    add
              dest-pathname  to the argument list. This takes the
              same options as -f.

              Note that "-foptions  pathname"  is  equivalent  to
              "-toptions pathname pathname".

       -a string
       -a=string
              Add string to the argument list.

       --cwd dir
       --cwd=dir
       --no-cwd
       --copy-cwd
              These  options  set  the  current working directory
              (cwd) for the process.

              --copy-cwd will use the calling process's cwd. This
              is the default.

              --no-cwd  unsets  the cwd, so that using a pathname
              relative to the cwd will give an error.

              --cwd sets the cwd to a directory given by a  path-
              name.

              In any case,  if the directory's pathname  does not
              exist in the namespace created for the process, the
              cwd will be left unset.

              These  options  also  affect  how  the pathnames in
              other arguments are interpreted. You can use multi-
              ple cwd arguments. An argument pathname is resolved
              relative to the most  recent  one.  The  final  cwd
              argument also sets the process's cwd.

       --no-default
              This  switches  off the default installation endow-
              ment, so that no files are granted implicitly. This
              must come before any -f or -t options.

       --x11  Grant  access  to  the  X11  Window System. This is
              equivalent to the options:

              -fl,socket /tmp/.X11-unix/
              -fl ~/.Xauthority

EXAMPLES
       In Bash:

       gcc -c foo.c -o foo.o

       In the Plash shell:

       gcc -c foo.c => -o foo.o + .

       This would become:

       plash-exec --prog=gcc  -a=-c  -fa=foo.c  -a=-o  -faw=foo.o  -f=.