pola-run — Run a program, giving it less authority than the caller
pola-run--prog
filename
[-f
[awls]...pathname
|-t
[awls]...pathname
pathname
|-a
string
|--cwd
dir
|--no-cwd
|--copy-cwd
]... [-B
] [--x11
] [--net
] [--powerbox
[--pet-name
name
]]
pola-run 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 callee's filesystem namespace.
pola-run provides a programmatic interface. It is intended to be used from Bash shell scripts and other programs. Since it works via the command line, it can be used from virtually any language, in contrast to a C API. pola-run 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 automatically.
pola-run 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.
Unlike the Plash shell, pola-run grants access to no files by default.
The -B
option will grant access to a fairly safe but large
installation endowment, which includes /usr, /bin and /lib.
(Currently this is different to the shell's default installation
endowment, which includes /etc as well.)
pola-run 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.
NB. The implementation is incomplete. Some things mentioned here aren't implemented yet.
For arguments that take one parameter, there are two forms to choose
from: "--arg
param
" and "--arg
=param
".
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
.
The filename is resolved in the callee's namespace, not the caller's namespace.
Note that if the executable is a "#!" script, access to the interpreter specified in the "#!" line will not be implicitly granted.
-f
[awls]...[,option
]... pathname
-f
[awls]...[,option
]...=pathname
Grant access to a file or directory (given by pathname
), and
optionally add pathname
to the argument list. This takes the
following single-letter options. The multi-character options must be
separated by commas.
a
Add pathname
to the argument list. Equivalent to
adding the argument "-a
pathname
".
w
Grant read/write access to the slot specified 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 "foLLow"). If
symbolic links are encountered when pola-run resolves
pathname
, these links will be followed. When the symlink
occurs at the last element in a pathname, this will cause
pola-run to grant access to both the symlink object and the
destination object (or the slots containing them, when the
w
option is used). If pathname
resolves to a
directory, this option does not affect the treatment of
symlinks inside the directory.
s
Grant permission to create symbolic links. (Only
relevant if w
is used.)
objrw
Grant read/write access to the file or directory
object, but not the slot, specified by pathname
. This is
useful for granting 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-pathname
), but attach
it to a different pathname in the file namespace(dest-pathname
).
Optionally add dest-pathname
to the argument list. This takes
the same options as -f
.
Note that "-f
options
pathname
" is not
exactly equivalent to "-t
options
pathname
pathname
". -t
will not introduce symlinks at the
directory components of dest-pathname
, and it will fail if there
are any symlinks in these locations.
-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 pathname.
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 multiple cwd arguments. An argument pathname is resolved relative to the most recent one. The final cwd argument also sets the process's cwd.
-B
Grant access to a default installation endowment. This is equivalent to the options:
-fl /usr -fl /bin -fl /lib -fl,objrw /dev/null -fl,objrw /dev/tty
--x11
Grant access to the X11 Window System. This is currently equivalent to the options:
-fl,socket /tmp/.X11-unix/ -fl ~/.Xauthority
In the future, --x11
may work using an X11 proxy.
--net
This grants access to some files that are important for accessing the Internet. When Plash gains the ability to deny a process access to the network, this option will gain the function of passing network access on to the callee.
Currently, this is equivalent to:
-fl /etc/resolv.conf -fl /etc/hosts -fl /etc/services
--powerbox
Grants the callee program an object "powerbox_req_filename" which can be used to open a file powerbox. A file powerbox is a file chooser dialog box which can grant the callee program access to files. The powerbox will dynamically attach files or directories into the callee program's file namespace.
Currently, it only makes sense to use this when the caller runs with
the user's namespace, since the file chooser will display directory
contents for the caller's namespace. In the future, the
--powerbox
option will be able to pass on the caller's
powerbox request object rather than always creating a new one.
--pet-name
name
This provides a name to use in the title bar of powerbox windows, so that the user can identify which application is making the request.