diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 159 |
1 files changed, 4 insertions, 155 deletions
@@ -1,156 +1,5 @@ - +# gVisor -[](https://storage.googleapis.com/gvisor-build-badges/build.html) -[](https://gitter.im/gvisor/community) - -## What is gVisor? - -**gVisor** is a user-space kernel, written in Go, that implements a substantial -portion of the Linux system surface. It includes an -[Open Container Initiative (OCI)][oci] runtime called `runsc` that provides an -isolation boundary between the application and the host kernel. The `runsc` -runtime integrates with Docker and Kubernetes, making it simple to run sandboxed -containers. - -## Why does gVisor exist? - -Containers are not a [**sandbox**][sandbox]. While containers have -revolutionized how we develop, package, and deploy applications, running -untrusted or potentially malicious code without additional isolation is not a -good idea. The efficiency and performance gains from using a single, shared -kernel also mean that container escape is possible with a single vulnerability. - -gVisor is a user-space kernel for containers. It limits the host kernel surface -accessible to the application while still giving the application access to all -the features it expects. Unlike most kernels, gVisor does not assume or require -a fixed set of physical resources; instead, it leverages existing host kernel -functionality and runs as a normal user-space process. In other words, gVisor -implements Linux by way of Linux. - -gVisor should not be confused with technologies and tools to harden containers -against external threats, provide additional integrity checks, or limit the -scope of access for a service. One should always be careful about what data is -made available to a container. - -## Documentation - -User documentation and technical architecture, including quick start guides, can -be found at [gvisor.dev][gvisor-dev]. - -## Installing from source - -gVisor currently requires x86\_64 Linux to build, though support for other -architectures may become available in the future. - -### Requirements - -Make sure the following dependencies are installed: - -* Linux 4.14.77+ ([older linux][old-linux]) -* [git][git] -* [Bazel][bazel] 1.2+ -* [Python][python] -* [Docker version 17.09.0 or greater][docker] -* C++ toolchain supporting C++17 (GCC 7+, Clang 5+) -* Gold linker (e.g. `binutils-gold` package on Ubuntu) - -### Building - -Build and install the `runsc` binary: - -``` -bazel build runsc -sudo cp ./bazel-bin/runsc/linux_amd64_pure_stripped/runsc /usr/local/bin -``` - -If you don't want to install bazel on your system, you can build runsc in a -Docker container: - -``` -make runsc -sudo cp ./bazel-bin/runsc/linux_amd64_pure_stripped/runsc /usr/local/bin -``` - -### Testing - -The test suite can be run with Bazel: - -``` -bazel test //... -``` - -or in a Docker container: - -``` -make unit-tests -make tests -``` - -### Using remote execution - -If you have a [Remote Build Execution][rbe] environment, you can use it to speed -up build and test cycles. - -You must authenticate with the project first: - -``` -gcloud auth application-default login --no-launch-browser -``` - -Then invoke bazel with the following flags: - -``` ---config=remote ---project_id=$PROJECT ---remote_instance_name=projects/$PROJECT/instances/default_instance -``` - -You can also add those flags to your local ~/.bazelrc to avoid needing to -specify them each time on the command line. - -### Using `go get` - -This project uses [bazel][bazel] to build and manage dependencies. A synthetic -`go` branch is maintained that is compatible with standard `go` tooling for -convenience. - -For example, to build `runsc` directly from this branch: - -``` -echo "module runsc" > go.mod -GO111MODULE=on go get gvisor.dev/gvisor/runsc@go -CGO_ENABLED=0 GO111MODULE=on go install gvisor.dev/gvisor/runsc -``` - -Note that this branch is supported in a best effort capacity, and direct -development on this branch is not supported. Development should occur on the -`master` branch, which is then reflected into the `go` branch. - -## Community & Governance - -The governance model is documented in our [community][community] repository. - -The [gvisor-users mailing list][gvisor-users-list] and -[gvisor-dev mailing list][gvisor-dev-list] are good starting points for -questions and discussion. - -## Security Policy - -See [SECURITY.md](SECURITY.md). - -## Contributing - -See [Contributing.md](CONTRIBUTING.md). - -[bazel]: https://bazel.build -[community]: https://gvisor.googlesource.com/community -[docker]: https://www.docker.com -[git]: https://git-scm.com -[gvisor-users-list]: https://groups.google.com/forum/#!forum/gvisor-users -[gvisor-dev-list]: https://groups.google.com/forum/#!forum/gvisor-dev -[oci]: https://www.opencontainers.org -[old-linux]: https://gvisor.dev/docs/user_guide/networking/#gso -[python]: https://python.org -[rbe]: https://blog.bazel.build/2018/10/05/remote-build-execution.html -[sandbox]: https://en.wikipedia.org/wiki/Sandbox_(computer_security) -[gvisor-dev]: https://gvisor.dev +This branch is a synthetic branch, containing only Go sources, that is +compatible with standard Go tools. See the master branch for authoritative +sources and tests. |