github.com/SagerNet/gvisor@v0.0.0-20210707092255-7731c139d75c/README.md (about)

     1  ![gVisor](g3doc/logo.png)
     2  
     3  [![Build status](https://badge.buildkite.com/3b159f20b9830461a71112566c4171c0bdfd2f980a8e4c0ae6.svg?branch=master)](https://buildkite.com/gvisor/pipeline)
     4  [![Issue reviver](https://github.com/google/gvisor/actions/workflows/issue_reviver.yml/badge.svg)](https://github.com/google/gvisor/actions/workflows/issue_reviver.yml)
     5  [![gVisor chat](https://badges.gitter.im/gvisor/community.png)](https://gitter.im/gvisor/community)
     6  [![code search](https://img.shields.io/badge/code-search-blue)](https://cs.opensource.google/gvisor/gvisor)
     7  
     8  ## What is gVisor?
     9  
    10  **gVisor** is an application kernel, written in Go, that implements a
    11  substantial portion of the Linux system surface. It includes an
    12  [Open Container Initiative (OCI)][oci] runtime called `runsc` that provides an
    13  isolation boundary between the application and the host kernel. The `runsc`
    14  runtime integrates with Docker and Kubernetes, making it simple to run sandboxed
    15  containers.
    16  
    17  ## Why does gVisor exist?
    18  
    19  Containers are not a [**sandbox**][sandbox]. While containers have
    20  revolutionized how we develop, package, and deploy applications, using them to
    21  run untrusted or potentially malicious code without additional isolation is not
    22  a good idea. While using a single, shared kernel allows for efficiency and
    23  performance gains, it also means that container escape is possible with a single
    24  vulnerability.
    25  
    26  gVisor is an application kernel for containers. It limits the host kernel
    27  surface accessible to the application while still giving the application access
    28  to all the features it expects. Unlike most kernels, gVisor does not assume or
    29  require a fixed set of physical resources; instead, it leverages existing host
    30  kernel functionality and runs as a normal process. In other words, gVisor
    31  implements Linux by way of Linux.
    32  
    33  gVisor should not be confused with technologies and tools to harden containers
    34  against external threats, provide additional integrity checks, or limit the
    35  scope of access for a service. One should always be careful about what data is
    36  made available to a container.
    37  
    38  ## Documentation
    39  
    40  User documentation and technical architecture, including quick start guides, can
    41  be found at [gvisor.dev][gvisor-dev].
    42  
    43  ## Installing from source
    44  
    45  gVisor builds on x86_64 and ARM64. Other architectures may become available in
    46  the future.
    47  
    48  For the purposes of these instructions, [bazel][bazel] and other build
    49  dependencies are wrapped in a build container. It is possible to use
    50  [bazel][bazel] directly, or type `make help` for standard targets.
    51  
    52  ### Requirements
    53  
    54  Make sure the following dependencies are installed:
    55  
    56  *   Linux 4.14.77+ ([older linux][old-linux])
    57  *   [Docker version 17.09.0 or greater][docker]
    58  
    59  ### Building
    60  
    61  Build and install the `runsc` binary:
    62  
    63  ```sh
    64  make runsc
    65  sudo cp ./bazel-bin/runsc/linux_amd64_pure_stripped/runsc /usr/local/bin
    66  ```
    67  
    68  ### Testing
    69  
    70  To run standard test suites, you can use:
    71  
    72  ```sh
    73  make unit-tests
    74  make tests
    75  ```
    76  
    77  To run specific tests, you can specify the target:
    78  
    79  ```sh
    80  make test TARGETS="//runsc:version_test"
    81  ```
    82  
    83  ### Using `go get`
    84  
    85  This project uses [bazel][bazel] to build and manage dependencies. A synthetic
    86  `go` branch is maintained that is compatible with standard `go` tooling for
    87  convenience.
    88  
    89  For example, to build and install `runsc` directly from this branch:
    90  
    91  ```sh
    92  echo "module runsc" > go.mod
    93  GO111MODULE=on go get gvisor.dev/gvisor/runsc@go
    94  CGO_ENABLED=0 GO111MODULE=on sudo -E go build -o /usr/local/bin/runsc gvisor.dev/gvisor/runsc
    95  ```
    96  
    97  Subsequently, you can build and install the shim binary for `containerd`:
    98  
    99  ```sh
   100  GO111MODULE=on sudo -E go build -o /usr/local/bin/containerd-shim-runsc-v1 gvisor.dev/gvisor/shim
   101  ```
   102  
   103  Note that this branch is supported in a best effort capacity, and direct
   104  development on this branch is not supported. Development should occur on the
   105  `master` branch, which is then reflected into the `go` branch.
   106  
   107  ## Community & Governance
   108  
   109  See [GOVERNANCE.md](GOVERNANCE.md) for project governance information.
   110  
   111  The [gvisor-users mailing list][gvisor-users-list] and
   112  [gvisor-dev mailing list][gvisor-dev-list] are good starting points for
   113  questions and discussion.
   114  
   115  ## Security Policy
   116  
   117  See [SECURITY.md](SECURITY.md).
   118  
   119  ## Contributing
   120  
   121  See [Contributing.md](CONTRIBUTING.md).
   122  
   123  [bazel]: https://bazel.build
   124  [docker]: https://www.docker.com
   125  [gvisor-users-list]: https://groups.google.com/forum/#!forum/gvisor-users
   126  [gvisor-dev]: https://gvisor.dev
   127  [gvisor-dev-list]: https://groups.google.com/forum/#!forum/gvisor-dev
   128  [oci]: https://www.opencontainers.org
   129  [old-linux]: https://gvisor.dev/docs/user_guide/networking/#gso
   130  [sandbox]: https://en.wikipedia.org/wiki/Sandbox_(computer_security)