diff options
| -rw-r--r-- | g3doc/user_guide/FAQ.md | 5 | ||||
| -rw-r--r-- | g3doc/user_guide/install.md | 184 | ||||
| -rw-r--r-- | g3doc/user_guide/quick_start/docker.md | 27 | ||||
| -rw-r--r-- | website/index.md | 2 |
4 files changed, 116 insertions, 102 deletions
diff --git a/g3doc/user_guide/FAQ.md b/g3doc/user_guide/FAQ.md index 8b5cff0ab..514fe3918 100644 --- a/g3doc/user_guide/FAQ.md +++ b/g3doc/user_guide/FAQ.md @@ -74,11 +74,10 @@ directories. ### I'm getting an error like: `panic: unable to attach: operation not permitted` or `fork/exec /proc/self/exe: invalid argument: unknown` {#runsc-perms} -Make sure that permissions and the owner is correct on the `runsc` binary. +Make sure that permissions is correct on the `runsc` binary. ```bash -sudo chown root:root /usr/local/bin/runsc -sudo chmod 0755 /usr/local/bin/runsc +sudo chmod a+rx /usr/local/bin/runsc ``` ### I'm getting an error like `mount submount "/etc/hostname": creating mount with source ".../hostname": input/output error: unknown.` {#memlock} diff --git a/g3doc/user_guide/install.md b/g3doc/user_guide/install.md index 9afdd264d..abb9e8582 100644 --- a/g3doc/user_guide/install.md +++ b/g3doc/user_guide/install.md @@ -5,6 +5,68 @@ > Note: gVisor supports only x86\_64 and requires Linux 4.14.77+ > ([older Linux](./networking.md#gso)). +## Install latest release {#install-latest} + +To download and install the latest release manually follow these steps: + +```bash +( + set -e + URL=https://storage.googleapis.com/gvisor/releases/release/latest + wget ${URL}/runsc ${URL}/runsc.sha512 + sha512sum -c runsc.sha512 + rm -f runsc.sha512 + sudo mv runsc /usr/local/bin + sudo chmod a+rx /usr/local/bin/runsc +) +``` + +To install gVisor with Docker, run the following commands: + +```bash +/usr/local/bin/runsc install +sudo systemctl restart docker +docker run --rm --runtime=runsc hello-world +``` + +For more details about using gVisor with Docker, see +[Docker Quick Start](./quick_start/docker.md) + +Note: It is important to copy `runsc` to a location that is readable and +executable to all users, since `runsc` executes itself as user `nobody` to avoid +unnecessary privileges. The `/usr/local/bin` directory is a good place to put +the `runsc` binary. + +## Install from an `apt` repository + +First, appropriate dependencies must be installed to allow `apt` to install +packages via https: + +```bash +sudo apt-get update && \ +sudo apt-get install -y \ + apt-transport-https \ + ca-certificates \ + curl \ + gnupg-agent \ + software-properties-common +``` + +Next, the configure the key used to sign archives and the repository: + +```bash +curl -fsSL https://gvisor.dev/archive.key | sudo apt-key add - +sudo add-apt-repository "deb https://storage.googleapis.com/gvisor/releases release main" +``` + +Now the runsc package can be installed: + +```bash +sudo apt-get update && sudo apt-get install -y runsc +``` + +If you have Docker installed, it will be automatically configured. + ## Versions The `runsc` binaries and repositories are available in multiple versions and @@ -21,12 +83,16 @@ Binaries are available for every commit on the `master` branch, and are available at the following URL: `https://storage.googleapis.com/gvisor/releases/master/latest/runsc` +`https://storage.googleapis.com/gvisor/releases/master/latest/runsc.sha512` -Checksums for the release binary are at: +You can use this link with the steps described in +[Install latest release](#install-latest). -`https://storage.googleapis.com/gvisor/releases/master/latest/runsc.sha512` +For `apt` installation, use the `master` to configure the repository: -For `apt` installation, use the `master` as the `${DIST}` below. +```bash +sudo add-apt-repository "deb https://storage.googleapis.com/gvisor/releases master main" +``` ### Nightly @@ -34,18 +100,22 @@ Nightly releases are built most nights from the master branch, and are available at the following URL: `https://storage.googleapis.com/gvisor/releases/nightly/latest/runsc` - -Checksums for the release binary are at: - `https://storage.googleapis.com/gvisor/releases/nightly/latest/runsc.sha512` +You can use this link with the steps described in +[Install latest release](#install-latest). + Specific nightly releases can be found at: `https://storage.googleapis.com/gvisor/releases/nightly/${yyyy-mm-dd}/runsc` Note that a release may not be available for every day. -For `apt` installation, use the `nightly` as the `${DIST}` below. +For `apt` installation, use the `nightly` to configure the repository: + +```bash +sudo add-apt-repository "deb https://storage.googleapis.com/gvisor/releases nightly main" +``` ### Latest release @@ -53,105 +123,47 @@ The latest official release is available at the following URL: `https://storage.googleapis.com/gvisor/releases/release/latest` -For `apt` installation, use the `release` as the `${DIST}` below. - -### Specific release - -A given release release is available at the following URL: - -`https://storage.googleapis.com/gvisor/releases/release/${yyyymmdd}` - -See the [releases][releases] page for information about specific releases. - -For `apt` installation of a specific release, which may include point updates, -use the date of the release, e.g. `${yyyymmdd}`, as the `${DIST}` below. - -> Note: only newer releases may be available as `apt` repositories. - -### Point release - -A given point release is available at the following URL: - -`https://storage.googleapis.com/gvisor/releases/release/${yyyymmdd}.${rc}` - -Note that `apt` installation of a specific point release is not supported. - -## Install from an `apt` repository +You can use this link with the steps described in +[Install latest release](#install-latest). -First, appropriate dependencies must be installed to allow `apt` to install -packages via https: +For `apt` installation, use the `release` to configure the repository: ```bash -sudo apt-get update && \ -sudo apt-get install -y \ - apt-transport-https \ - ca-certificates \ - curl \ - gnupg-agent \ - software-properties-common +sudo add-apt-repository "deb https://storage.googleapis.com/gvisor/releases release main" ``` -Next, the key used to sign archives should be added to your `apt` keychain: - -```bash -curl -fsSL https://gvisor.dev/archive.key | sudo apt-key add - -``` +### Specific release -Based on the release type, you will need to substitute `${DIST}` below, using -one of: +A given release release is available at the following URL: -* `master`: For HEAD. -* `nightly`: For nightly releases. -* `release`: For the latest release. -* `${yyyymmdd}`: For a specific releases (see above). +`https://storage.googleapis.com/gvisor/releases/release/${yyyymmdd}` -The repository for the release you wish to install should be added: +You can use this link with the steps described in +[Install latest release](#install-latest). -```bash -sudo add-apt-repository "deb https://storage.googleapis.com/gvisor/releases ${DIST} main" -``` +See the [releases](https://github.com/google/gvisor/releases) page for +information about specific releases. -For example, to install the latest official release, you can use: +For `apt` installation of a specific release, which may include point updates, +use the date of the release for repository, e.g. `${yyyymmdd}`. ```bash -sudo add-apt-repository "deb https://storage.googleapis.com/gvisor/releases release main" +sudo add-apt-repository "deb https://storage.googleapis.com/gvisor/releases yyyymmdd main" ``` -Now the runsc package can be installed: - -```bash -sudo apt-get update && sudo apt-get install -y runsc -``` +> Note: only newer releases may be available as `apt` repositories. -If you have Docker installed, it will be automatically configured. +### Point release -## Install directly +A given point release is available at the following URL: -The binary URLs provided above can be used to install directly. For example, the -latest nightly binary can be downloaded, validated, and placed in an appropriate -location by running: +`https://storage.googleapis.com/gvisor/releases/release/${yyyymmdd}.${rc}` -```bash -( - set -e - URL=https://storage.googleapis.com/gvisor/releases/nightly/latest - wget ${URL}/runsc - wget ${URL}/runsc.sha512 - sha512sum -c runsc.sha512 - rm -f runsc.sha512 - sudo mv runsc /usr/local/bin - sudo chown root:root /usr/local/bin/runsc - sudo chmod 0755 /usr/local/bin/runsc -) -``` +You can use this link with the steps described in +[Install latest release](#install-latest). -**It is important to copy this binary to a location that is accessible to all -users, and ensure it is executable by all users**, since `runsc` executes itself -as user `nobody` to avoid unnecessary privileges. The `/usr/local/bin` directory -is a good place to put the `runsc` binary. +Note that `apt` installation of a specific point release is not supported. After installation, try out `runsc` by following the [Docker Quick Start](./quick_start/docker.md) or [OCI Quick Start](./quick_start/oci.md). - -[releases]: https://github.com/google/gvisor/releases diff --git a/g3doc/user_guide/quick_start/docker.md b/g3doc/user_guide/quick_start/docker.md index 6ad594ecc..ee842e453 100644 --- a/g3doc/user_guide/quick_start/docker.md +++ b/g3doc/user_guide/quick_start/docker.md @@ -22,18 +22,6 @@ named "runsc" by default. sudo runsc install ``` -You may also wish to install a runtime entry for debugging. The `runsc install` -command can accept options that will be passed to the runtime when it is invoked -by Docker. - -```bash -sudo runsc install --runtime runsc-debug -- \ - --debug \ - --debug-log=/tmp/runsc-debug.log \ - --strace \ - --log-packets -``` - You must restart the Docker daemon after installing the runtime. Typically this is done via `systemd`: @@ -85,6 +73,21 @@ $ docker run --runtime=runsc -it ubuntu dmesg Note that this is easily replicated by an attacker so applications should never use `dmesg` to verify the runtime in a security sensitive context. +## Options + +You may also wish to install a runtime entry with different options. The `runsc +install` command can accept flags that will be passed to the runtime when it is +invoked by Docker. For example, to install a runtime with debugging enabled, run +the following: + +```bash +sudo runsc install --runtime runsc-debug -- \ + --debug \ + --debug-log=/tmp/runsc-debug.log \ + --strace \ + --log-packets +``` + Next, look at the different options available for gVisor: [platform][platforms], [network][networking], [filesystem][filesystem]. diff --git a/website/index.md b/website/index.md index 84f877d49..c6cd477c2 100644 --- a/website/index.md +++ b/website/index.md @@ -5,7 +5,7 @@ <div class="col-md-6"> <p>gVisor is an <b>application kernel</b> for <b>containers</b> that provides efficient defense-in-depth anywhere.</p> <p style="margin-top: 20px;"> - <a class="btn" href="/docs/user_guide/quick_start/docker/">Quick start <i class="fas fa-arrow-alt-circle-right ml-2"></i></a> + <a class="btn" href="/docs/user_guide/install/">Get started <i class="fas fa-arrow-alt-circle-right ml-2"></i></a> <a class="btn" href="/docs/">Learn More <i class="fas fa-arrow-alt-circle-right ml-2"></i></a> </p> </div> |