sandboxfs.1

.\" Copyright 2017 Google Inc.
.\"
.\" Licensed under the Apache License, Version 2.0 (the "License"); you may not
.\" use this file except in compliance with the License.  You may obtain a copy
.\" of the License at:
.\"
.\"     http://www.apache.org/licenses/LICENSE-2.0
.\"
.\" Unless required by applicable law or agreed to in writing, software
.\" distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
.\" WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the
.\" License for the specific language governing permissions and limitations
.\" under the License.
.Dd January 15, 2019
.Dt SANDBOXFS 1
.Os
.Sh NAME
.Nm sandboxfs
.Nd A virtual file system for sandboxing
.Sh SYNOPSIS
.Nm
.Op Fl -allow Ar who
.Op Fl -cpu_profile Ar path
.Op Fl -input Ar path
.Op Fl -help
.Op Fl -mapping Ar type:mapping:target
.Op Fl -output Ar path
.Op Fl -ttl Ar duration
.Op Fl -version
.Ar mount_point
.Sh DESCRIPTION
.Nm
is a FUSE file system that exposes a combination of multiple files and
directories from the host's file system in the form of a virtual tree with an
arbitrary layout.
You can think of a sandbox as an arbitrary view into the host's file system with
different access privileges per directory.
.Pp
.Nm
is designed to allow running commands with limited access to the file system by
using the virtual tree as their new root, and to do so consistently across a
variety of platforms.
.Pp
The sandbox instance mounted at
.Ar mount_point
is initially configured with the mapping specifications provided via repeated
instances of
.Fl -mapping .
Once running, the mount point can be reconfigured any number of times:
.Nm
listens for reconfiguration requests on the file specified by
.Fl -input
and reconfigures the mappings as requested, emiting a response on the file
specified by
.Fl -output .
.Pp
The following flags are recognized:
.Bl -tag -width XXXX
.It Fl -allow Ar who
Specifies who should have access to the file system.
.Ar who
must be one of:
.Sq other
to indicate that everyone, including root, can access the file system;
.Sq root
to indicate that only the current user and root can access the file system; and
.Sq self
to indicate that only the current user can access the file system.
.Pp
The default value is
.Sq self
because the standard FUSE configuration does not allow more relaxed
permissions, and it would be a pity if you couldn't run
.Nm
successfully without additional configuration.
To change this behavior, add
.Sq user_allow_other
to
.Pa /etc/fuse.conf
on Linux or set the
.Sq vfs.generic.osxfuse.tunables.allow_other
.Xr sysctl 8
tunable to 1 on macOS.
.Pp
Note that, at least on macOS, you will need to consider granting
.Sq other
permissions if you intend to run signed binaries through the sandbox.
This is because the
.Xr amfid 8
daemon, which implements the signature validation, runs as a different user
and must be able to access the executables.
.It Fl -cpu_profile Ar path
Enables CPU profiling and stores the pprof log to the given
.Ar path .
This feature is only available if
.Nm
was built with gperftools support (i.e. with the compile-time
.Sq profiler
feature).
Passing this flag when support is not enabled results in an error.
.It Fl -input Ar path
Points to the file from which to read new configuration requests, or
.Sq -
(the default) for stdin.
See the
.Sx Reconfigurations
subsection for details on the contents and behavior of the input file.
.It Fl -help
Prints global help details and exits.
Specifying this flag causes all other valid flags and arguments to be ignored.
.It Fl -mapping Ar type:mapping:target
Registers a new mapping.
This flag can be given an arbitrary number of times as long as the same
.Ar mapping
is not repeated.
See the
.Sx Mapping specifications
subsection for details on how a mapping is specified.
.It Fl -output Ar path
Points to the file to which to write confirmations of reconfiguration, or
.Sq -
(the default) for stdout.
See the
.Sx Reconfigurations
subsection for details on the contents and behavior of the output file.
.It Fl -ttl Ar duration
Specifies how long the kernel is allowed to cache file metadata for.
The duration is currently specified as a number of seconds followed by the
.Sq s
suffix.
.It Fl -version
Prints version information and exits.
Specifying this flag causes all other valid flags and arguments to be ignored
except for
.Fl -help ,
which has priority over this one.
.Pp
The first line printed to stdout is machine parseable and follows the following
structure:
.Bd -literal -offset indent
sandboxfs MAJOR.MINOR[.ADDITIONAL OPTIONAL QUALIFIERS]
.Ed
.Pp
Programs automating invocations of
.Nm
can use this information to determine the correct command-line syntax to use.
.El
.Ss Mapping specifications
The basic concept behind a
.Nm
instance is the
.Em mapping specification .
A mapping specification defines how an arbitrary location within the sandbox
relates to another arbitrary location on the host file system.
Mapping specifications have three components: the
.Em target ,
which is a path to a file or directory into the host file system (i.e. outside
of the mount point); the
.Em mapping ,
which is an absolute path within the mount point in which the target is exposed;
and the
.Em type ,
which specifies the permissions of the mapping.
.Pp
The target must exist but the mapping may not: in particular, any path
subcomponents of the mapping that have not been previously mapped
within the sandbox will be created as virtual read-only nodes.
This means that the ordering of the mappings matters.
.Pp
For example: consider a
.Nm
instance mounted onto
.Pa /mnt
that maps
.Pa /my/custom/bin
to the
.Pa /usr/bin
target.
With this setup,
.Pa /mnt/my/custom/bin
will expose the contents of the real
.Pa /usr/bin
directory.
.Pp
The following types are currently supported:
.Bl -tag -width XXXX
.It ro
A read-only mapping.
The contents of the target are exposed verbatim at the mapping point and they
cannot be modified through the mount point.
Any write access will result in an
.Dv EPERM .
.It rw
A read/write mapping.
The contents of the target are exposed verbatim at the mapping point and they
can be modified at will through the mount point.
Writes through the moint point are applied immediately to the underlying target
directory.
.El
.Ss Reconfigurations
While a mount point is live,
.Nm
listens for reconfiguration requests on the file specified by
.Fl -input
and writes confirmations to the file specified by
.Fl -output .
These two files essentially implement a rudimentary RPC system subject to
change.
.Pp
The mount point can be configured any number of times while mounted,
which allows for processes to efficiently change the view of the sandbox at will
without having to remount it.
Closing the input file causes
.Nm
to freeze its configuration and not accept any more requests for
reconfiguration, but the file system will continue to operate normally until
it is either unmounted or signaled.
.Pp
Reconfiguration requests can be issued at any time.
However, it is impossible for
.Nm
to properly deal with ongoing file system operations or with open file handles
in a deterministic manner.
Due to this, the behavior of ongoing file system activity while a
reconfiguration happens is unspecified but can be assumed to be stable (i.e.
.Nm
will not deadlock nor crash).
As a result, it is highly recommended that you only send reconfiguration
requests when you know that the file system is quiescent.
.Pp
Configuration requests are formatted as a JSON map followed by a single blank
line.
A configuration request is an ordered sequence of
.Em steps .
A step is a dictionary with keys
.Sq Map
and
.Sq Unmap
which represent a single map or unmap operation.
Exactly one key must be present in each step.
Map operations add new mappings to the file system and unmap operations remove
existing mappings.
.Pp
A map operation is specified as a dictionary with the following keys:
.Sq Mapping
and
.Sq Target ,
which define the mapping paths, and
.Sq Writable ,
which if set to true indicates a read/write mapping.
The mapping must not yet exist in the file system.
.Pp
An unmap operation is specified as a non-empty string containing the path of
the mapping to remove.
The path must exist in the file system and must represent a mapping (not a file
from an underlying file system).
If a mapping operation created intermediate empty directory components,
unmapping the leaf of such path does
.Em not
cause those intermediate components to be unmapped: it is the responsibility of
the caller to do so, for simplicity reasons.
.Pp
Once
.Nm
accepts a valid reconfiguration request and the file system is fully
reconfigured, the single line
.Sq Done
is written to the output file.
.Sh EXIT STATUS
.Nm
exits with 0 if the file system was both mounted and unmounted cleanly; 1 on a
controlled error condition encountered during the execution of a command; or 2
on a usage error.
.Pp
Sending a termination signal to
.Nm
will cause the file system to exit in a controlled manner, ensuring that the
mount point is released.
If the file system is busy, the signal will be queued until all open file
descriptors on the file system are released at which point the file system
will try to exit cleanly again.
Note that, due to limitations in signal handling in Rust (which is the language
in which
.Nm
is implemented), the reception of a signal will cause
.Nm
to return 1 instead of terminating with a signal condition.
.Sh ENVIRONMENT
.Nm
recognizes the following environment variables:
.Bl -tag -width XXXX
.It Va RUST_LOG
Sets the maximum level of logging messages sent to stderr.
Possible values include
.Sq error ,
.Sq warn ,
.Sq info
and
.Sq debug ,
though many more syntaxes are supported.
See the documentation for Rust's
.Sq env_logger
crate for more details.
.El
.Pp
.Nm
may recognize other standard Rust variables like
.Va RUST_BACKTRACE
but the list above attempts to describe the ones a user may find most useful.
.Sh EXAMPLES
The following example configures a sandbox that maps the whole host's
file system but clears
.Pa /tmp
to point into a sandbox-specific writable directory:
.Bd -literal -offset indent
sandboxfs --mapping=ro:/:/ --mapping=rw:/tmp:/tmp/fresh-tmp /mnt
.Ed
.Pp
This example modifies an existing sandbox by adding a new mapping for
.Pa /tmp
and redoing the mapping for
.Pa /foo
by pointing it at another location.
.Bd -literal -offset indent
[
    {"Map": {"Mapping": "/tmp", "Target": "/tmp/abc", "Writable": true}},
    {"Unmap": "/foo"},
    {"Map": {"Mapping": "/foo/bar", "Target": "/", "Writable": false}}
]
.Ed
.Sh AUTHORS
.An -nosplit
The
.Nm
was originally developed as a Go program by
.An Pallav Agarwal
.Aq pallavag@google.com
with guidance from
.An Julio Merino
.Aq jmmv@google.com .
The program was later reimplemented in Rust by the latter.
.Sh BUGS
The following are known limitations of
.Nm :
.Bl -bullet
.It
Hard links are not supported.
.It
On macOS, mapping the same external file or directory under two different
locations within the mount point results in undefined behavior.
Writes may not be reflected at both mapped locations at the same time, which
can lead to data corruption.
This is true even for read-only mappings because each separate view within
the mount point may have cached different contents, returning different data
than what's truly on disk.
.It
The
.Fl -allow Ar root
setting does not work on Linux; use
.Fl -allow Ar other
as the alternative.
See https://github.com/bazil/fuse/issues/144 for details.
.It
It is currently impossible to terminate
.Nm
cleanly while the file system is busy.
Signals received while the file system is in use will be queued as described in
.Sx EXIT STATUS
and fatal signals will cause
.Nm
to leak the mount point (possibly irrecoverably without a reboot because of
kernel bugs).
.It
Any explicitly-mapped directories and any scaffold directories (those
directories that appear to represent intermediate path components that do not
exist anywhere else in the file system) cannot be removed.
Attempts to remove them will result in a
.Dq permission denied
error.
While it could be possible to implement some different behavior, this is what
.Nm
currently exposes.
You may or may not consider this to be a bug.
.It
Node data is cached in-memory for all files accessed through a
.Nm
instance in order to offer good performance across reconfigurations.
However, this cache does not currently implement any expiration policy, which
means that memory usage can grow unboundedly if many different files are
mapped and accessed through the sandbox.
.It
If a FIFO is used for
.Fl input ,
.Nm
will block until a separate process opens the FIFO for writing.
This happens even before the file system starts serving, which means the file
system is not usable until the FIFO is opened.
.It
While it is possible to reconfigure the entries of the root directory of a
running file system, it is not possible to reconfigure the root mapping itself
to point to a different location or to change its writability properties.
.It
Unmapping entries doesn't fully work.
The FUSE library that
.Nm
currently uses does not support sending cache invalidation requests to the
kernel, which means unmapped entries will not vanish immediately from the
file system.
You may be able to mitigate this by setting a low node TTL with the
.Fl -ttl
flag, but this doesn't work on macOS either because OSXFUSE does not honor
node TTLs.
.El