Name

pola-run — Run a program, giving it less authority than the caller

Synopsis

pola-run
  --prog filename
  [ -f[awls]... pathname
  | -t[awls]... pathname pathname
  | -a string
  | --cwd dir
  | --no-cwd
  | --copy-cwd ]...
  [-B] [--x11] [--net]

Description

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.

Options

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.

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 executable 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 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 "-foptions pathname" is not exactly equivalent to "-toptions 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

Examples

In Bash:

gcc -c foo.c -o foo.o

In the Plash shell:

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

This would become:

pola-run -B --prog=gcc  -a=-c  -fa=foo.c  -a=-o  -faw=foo.o  -f=.

Run Bash with the same filesystem namespace as the caller. This is useful for testing Plash:

pola-run -fw=/ --prog /bin/bash

See also

plash, plash-socket-publish

/usr/share/doc/plash

Author

Mark Seaborn <mseaborn@onetel.com>