Skip to content

Latest commit

 

History

History
128 lines (88 loc) · 5.1 KB

INSTALL.md

File metadata and controls

128 lines (88 loc) · 5.1 KB
Raw

Installation instructions

Using the macOS installer

  1. Download and install OSXFUSE.

  2. Download the sandboxfs-<release>-<date>-macos.pkg file attached to the latest release in the releases page.

  3. Double-click the downloaded file and follow the instructions.

Should you want to uninstall sandboxfs at any point, you can run /usr/local/share/sandboxfs/uninstall.sh to cleanly remove all installed files.

Using the generic Linux pre-built binaries

If your Linux distribution does not provide sandboxfs packages on its own, you can try using the prebuilt versions we supply. These assume that you have certain versions of shared libraries in the right location, so your mileage may vary when attempting to use these. If the binaries do not work, you'll have to build sandboxfs from the sources as described later on.

  1. Install FUSE. The specific steps will depend on your distribution but here are some common examples:

    • Debian, Ubuntu: apt install libfuse2.
    • Fedora: dnf install fuse-libs.

  2. Download the sandboxfs-<release>-<date>-linux-<arch>.tgz file attached to the latest release in the releases page.

  3. Extract the downloaded file in the prefix where you want sandboxfs to be available. The most common location for a system-wide installation is /usr/local so do:

    tar xzv -C /usr/local -f .../path/to/downloaded.tgz

    You can also install sandboxfs under your home directory if you do not have administrator privileges, for example under ~/local.

  4. Verify that the binary can start by running it at least once. If it does start (because it can find all required shared libraries), you can be fairly confident that it will work.

Should you want to uninstall sandboxfs at any point, you can run .../share/sandboxfs/uninstall.sh from the prefix in which you unpacked the pre-built binaries to cleanly remove all installed files.

From crates.io

  1. Download and install Rust. If you already had it installed, make sure you are on a new-enough version by running rustup update.

  2. Install FUSE and pkg-config. The specific steps will depend on your system but here are some common examples:

    • Debian, Ubuntu: apt install libfuse-dev pkg-config.
    • Fedora: dnf install fuse-devel pkgconf-pkg-config.
    • macOS: Visit the OSXFUSE homepage and try brew install pkg-config.

  3. Run cargo install sandboxfs.

From a GitHub checkout

  1. Download and install Rust. If you already had it installed, make sure you are on a new-enough version by running rustup update.

  2. Download and install FUSE for your system. On Linux this will vary on a distribution basis, and on macOS you can install OSXFUSE.

  3. Download and install pkg-config or pkgconf.

  4. Run ./configure to generate the scripts that will allow installation.

    1. The default installation path is /usr/local but you can customize it to any other location by passing the flag --prefix=/usr/local.

    2. The build scripts will use cargo from your path but you can set a different location by passing the --cargo=/path/to/cargo flag.

    3. The build scripts will use go from your path but you can set a different location by passing the --goroot=/path/to/goroot flag. You can also use the magic none value to disable Go usage, but this will prevent running the integration tests or the code linter.

  5. Run make release to download all required dependencies and build the final binary.

    1. You could also run cargo build --release. This package is intended to work just fine with the standard Cargo toolchain.

  6. Run make install to put the built binary and all supporting files in place.

    • You will (most likely) need superuser permissions to install under /usr/local, so run the previous command with sudo.

Profiling support

sandboxfs has optional support for the gperftools profiling tools. If you have that package installed, you can pass --features=profiling to the configure script and sandboxfs's --cpu_profile flag will become functional.

macOS only: Enable "allow other" support in OSXFUSE

In order to run system binaries within a sandboxfs mount point (which is the primary goal of using sandboxfs), you must enable OSXFUSE's "allow other" support; otherwise, necessary core macOS security services will deny executions.

To do this, run the following for a one-time change:

sudo sysctl -w vfs.generic.osxfuse.tunables.allow_other=1

Note that you cannot do this via /etc/sysctl.conf because the OSXFUSE kernel extension has not yet been loaded when this file is parsed.

The macOS installer configures your system to do this automatically at every boot by using a launch agent.