Documentation (#25)

* .goreleaser.yml: automatically assign capabilities in postinstall script

* Document how to install Vetu in different environments

* Expand the "Usage" section a bit and document VM's location on disk

* Explain the difference between {QEMU,Firecracker,Cloud Hypervisor}

And document networking options.

* Automatically fetch Cloud Hypervisor and Rust Hypervisor Firmware

But only if Cloud Hypervisor and EDK2 firmware
is  not available on the system.

* old-school → traditional

Co-authored-by: Fedor Korotkov <[email protected]>

* Highlight the features inherited from Tart

* Decipher the Vetu name in the main heading

Co-authored-by: Fedor Korotkov <[email protected]>

* Remove bold-parts of the deciphered name as they're ineffectual

* Better highlight the Tart-inherited benefits

Co-authored-by: Fedor Korotkov <[email protected]>

* Do not use path.Join() to join URL parts

---------

Co-authored-by: Fedor Korotkov <[email protected]>

Author: edigaryev

.goreleaser.yml

@@ -34,9 +34,8 @@ nfpms:
     maintainer: [email protected]
     description: CLI for executing Cirrus tasks locally and in any CI
     section: misc
-    dependencies:
-      - cloud-hypervisor
-      - edk2-cloud-hypervisor
+    scripts:
+      postinstall: "scripts/postinstall.sh"
     formats:
       - deb
       - rpm

INSTALL.md

@@ -0,0 +1,85 @@
+# Index
+
+* [Debian-based distributions](#debian-based-distributions) (Debian, Ubuntu, etc.)
+* [RPM-based distributions](#rpm-based-distributions) (Fedora, CentOS, etc.)
+* [Prebuilt Binary](#prebuilt-binary)
+* [From Source](#from-source)
+
+# Prerequisites
+
+Make sure that your user has the `/dev/kvm` access. On most distributions, this can be accomplished by adding the current user to the `kvm` group:
+
+```shell
+sudo gpasswd -a $USER kvm
+```
+
+Once added to a group, you will need to re-login for the changes to take effect.
+
+## Installation
+
+## Debian-based distributions
+
+First, make sure that you've installed the APT transport for downloading packages via HTTPS and common X.509 certificates:
+
+```shell
+sudo apt-get update && sudo apt-get -y install apt-transport-https ca-certificates
+```
+
+Then, add the Cirrus Labs repository:
+
+```shell
+echo "deb [trusted=yes] https://apt.fury.io/cirruslabs/ /" | sudo tee /etc/apt/sources.list.d/cirruslabs.list
+```
+
+Now you can update the package index files and install the Vetu:
+
+```shell
+sudo apt-get update && sudo apt-get -y install vetu
+```
+
+## RPM-based distributions
+
+First, create a `/etc/yum.repos.d/cirruslabs.repo` file with the following contents:
+
+```
+[cirruslabs]
+name=Cirrus Labs Repo
+baseurl=https://yum.fury.io/cirruslabs/
+enabled=1
+gpgcheck=0
+```
+
+Now you can install the Vetu:
+
+```shell
+sudo yum -y install vetu
+```
+
+## Prebuilt Binary
+
+Check the [releases page](https://github.com/cirruslabs/vetu/releases) for a pre-built `vetu` binary for your platform.
+
+Here's a one-liner for Linux to download the latest release:
+
+```bash
+curl -L -o vetu https://github.com/cirruslabs/vetu/releases/latest/download/vetu-linux-$(uname -m) && sudo mv vetu /usr/bin/vetu && sudo chmod +x /usr/bin/vetu && sudo setcap cap_net_raw,cap_net_admin+eip /usr/bin/vetu
+```
+
+## From Source
+
+If you have [Golang](https://golang.org/) 1.21 or newer installed, you can run:
+
+```
+go install github.com/cirruslabs/vetu/...@latest
+```
+
+This will build and place the `vetu` binary in `$GOPATH/bin`.
+
+Vetu binary also needs some capabilities assigned to it:
+
+```shell
+sudo setcap cap_net_raw,cap_net_admin+eip $GOPATH/bin/vetu
+```
+
+To be able to run `vetu` command from anywhere, make sure the `$GOPATH/bin` directory is added to your `PATH`
+environment variable (see [article in the Go wiki](https://github.com/golang/go/wiki/SettingGOPATH) for more details).

README.md

@@ -1,3 +1,57 @@
-# vetu
+# **vetu** - Virtualization that is Easy To Use
 
-_vetu_ is virtualization toolset to effortlessly run Cloud Hypervisor-backed virtual machines on Linux hosts.
+_vetu_ is virtualization toolset to effortlessly run [Cloud Hypervisor](https://www.cloudhypervisor.org/)-backed virtual machines on Linux hosts.
+
+We say effortlessly, because the existing virtualization solutions like the traditional [QEMU](https://www.qemu.org/) and the new-wave [Firecracker](https://firecracker-microvm.github.io/) and Cloud Hypervisor provide lots of options and require users to essentially build a tooling on top of them to be able to simply run a basic VM.
+
+Vetu builds on the success of [Tart](https://tart.run/) and abstracts all these peculiarities and makes the virtualization as easy as running containers.
+
+Here are just some of the cool features that Vetu inherited from Tart:
+
+* Ability to easily distribute VM images by integrating with OCI-compatible container registries. Push and pull virtual machines like they are containers.
+* Effortless SSH'ing into VMs (see [Usage](#usage) for an example)
+* [Cirrus CLI](https://github.com/cirruslabs/cirrus-cli) integration
+
+## Installation
+
+* [Debian-based distributions](INSTALL.md#debian-based-distributions) (Debian, Ubuntu, etc.)
+* [RPM-based distributions](INSTALL.md#rpm-based-distributions) (Fedora, CentOS, etc.)
+* [Prebuilt Binary](INSTALL.md#prebuilt-binary)
+* [From Source](INSTALL.md#from-source)
+
+## Usage
+
+Try running a Vetu VM on your Linux machine with `arm64` processor:
+
+```shell
+vetu clone ghcr.io/cirruslabs/ubuntu:latest ubuntu
+vetu run ubuntu
+```
+
+The default username is `admin` and password is `admin`. The machine is only reachable from the localhost with the default configuration, and you can connect to it over SSH using the following command:
+
+```shell
+ssh admin@$(vetu ip ubuntu)
+```
+
+## Networking options
+
+### Default (NAT)
+
+The default NAT networking is powered by the [gVisor's TCP/IP stack](https://gvisor.dev/docs/user_guide/networking/) and has an advantage of requiring no configuration on the user's end.
+
+The main disadvantage is the reduced speed, because all the routing and processing is also done in the software (in the Vetu process), in addition to the kernel.
+
+However, this choice is still fast enough to run most of the tasks, for example, provisioning a Linux distro and installing the packages.
+
+### Bridged
+
+Bridged networking can be enabling by specifying `--net-bridged=BRIDGE_INTERFACE_NAME` argument to `vetu run` and has an advantage of being fast, because all the processing and routing is done in the kernel.
+
+The main disadvantage is that this choice requires the system administrator to properly configure the bridge interface, IP forwarding, DHCP server (if required by the VM) and the packet filter to provide adequate network isolation.
+
+## FAQ
+
+### VM location on disk
+
+Vetu stores all it's files in `~/.vetu/` directory. Local images that you can run are stored in `~/.vetu/vms/`. Remote images are pulled into `~/.vetu/cache/OCIs/`.

internal/binaryfetcher/binaryfetcher.go

@@ -0,0 +1,78 @@
+package binaryfetcher
+
+import (
+	"context"
+	"fmt"
+	"github.com/cirruslabs/vetu/internal/homedir"
+	"io"
+	"net/http"
+	"os"
+	"path/filepath"
+)
+
+func Fetch(ctx context.Context, downloadURL string, binaryName string, executable bool) (string, error) {
+	// Determine the binary path
+	binaryPath, err := binaryPath(binaryName)
+	if err != nil {
+		return "", err
+	}
+
+	// Use the cached binary if possible
+	if _, err := os.Stat(binaryPath); err == nil {
+		return binaryPath, nil
+	}
+
+	// Download and cache the binary if not available in the cache
+	client := http.Client{}
+
+	request, err := http.NewRequestWithContext(ctx, http.MethodGet, downloadURL, nil)
+	if err != nil {
+		return "", err
+	}
+
+	resp, err := client.Do(request)
+	if err != nil {
+		return "", err
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != http.StatusOK {
+		return "", fmt.Errorf("failed to fetch %q binary from %s: HTTP %d",
+			binaryName, downloadURL, resp.StatusCode)
+	}
+
+	binaryFile, err := os.Create(binaryPath)
+	if err != nil {
+		return "", err
+	}
+	defer binaryFile.Close()
+
+	if _, err := io.Copy(binaryFile, resp.Body); err != nil {
+		return "", err
+	}
+
+	// Make the binary executable if requested
+	if executable {
+		if err := binaryFile.Chmod(0755); err != nil {
+			return "", err
+		}
+	}
+
+	return binaryPath, nil
+}
+
+func binaryPath(binaryName string) (string, error) {
+	homeDir, err := homedir.Path()
+	if err != nil {
+		return "", err
+	}
+
+	baseDir := filepath.Join(homeDir, "cache", "bin")
+
+	// Ensure that the base directory exists
+	if err := os.MkdirAll(baseDir, 0755); err != nil {
+		return "", err
+	}
+
+	return filepath.Join(baseDir, binaryName), nil
+}

internal/externalbinary/firmware/firmware.go

@@ -0,0 +1,44 @@
+package firmware
+
+import (
+	"context"
+	"fmt"
+	"github.com/cirruslabs/vetu/internal/binaryfetcher"
+	"os"
+	"runtime"
+)
+
+const (
+	edk2BinaryPath = "/usr/share/cloud-hypervisor/CLOUDHV_EFI.fd"
+	baseURL        = "https://github.com/cirruslabs/rust-hypervisor-firmware/releases/latest/download/"
+)
+
+var goarchToDownloadURL = map[string]string{
+	"amd64": baseURL + "hypervisor-fw",
+	"arm64": baseURL + "hypervisor-fw-aarch64",
+}
+
+func Firmware(ctx context.Context) (string, string, error) {
+	// Always prefer the EDK2 firmware installed on the system
+	_, err := os.Stat(edk2BinaryPath)
+	if err == nil {
+		return edk2BinaryPath, "EDK2 firmware", nil
+	}
+
+	// Fall back to downloading the Rust Hypervisor Firmware from GitHub
+	downloadURL, ok := goarchToDownloadURL[runtime.GOARCH]
+	if !ok {
+		return "", "", fmt.Errorf("no EDK2 firmware installed on the system "+
+			"and architecture %q is not available in Rust Hypervisor Firmware's GitHub releases", runtime.GOARCH)
+	}
+
+	fmt.Printf("no EDK2 firmware installed on the system, downloading Rust Hypervisor Firmware "+
+		"from %s...\n", downloadURL)
+
+	binaryPath, err := binaryfetcher.Fetch(ctx, downloadURL, "hypervisor-fw", true)
+	if err != nil {
+		return "", "", err
+	}
+
+	return binaryPath, "Rust Hypervisor Firmware", nil
+}

internal/externalcommand/cloudhypervisor/cloudhypervisor.go

@@ -2,15 +2,39 @@ package cloudhypervisor
 
 import (
 	"context"
+	"fmt"
+	"github.com/cirruslabs/vetu/internal/binaryfetcher"
 	"os/exec"
+	"runtime"
 )
 
-const binaryName = "cloud-hypervisor"
+const (
+	binaryName = "cloud-hypervisor"
+	baseURL    = "https://github.com/cloud-hypervisor/cloud-hypervisor/releases/latest/download/"
+)
+
+var goarchToDownloadURL = map[string]string{
+	"amd64": baseURL + "cloud-hypervisor-static",
+	"arm64": baseURL + "cloud-hypervisor-static-aarch64",
+}
 
 func CloudHypervisor(ctx context.Context, args ...string) (*exec.Cmd, error) {
+	// Always prefer the Cloud Hypervisor binary in PATH
 	binaryPath, err := exec.LookPath(binaryName)
 	if err != nil {
-		return nil, err
+		// Fall back to downloading the Cloud Hypervisor binary from GitHub
+		downloadURL, ok := goarchToDownloadURL[runtime.GOARCH]
+		if !ok {
+			return nil, fmt.Errorf("no %q binary found in PATH and architecture %q "+
+				"is not available in Cloud Hypervisor's GitHub releases", binaryName, runtime.GOARCH)
+		}
+
+		fmt.Printf("no %q binary found in PATH, downloading it from %s...\n", binaryName, downloadURL)
+
+		binaryPath, err = binaryfetcher.Fetch(ctx, downloadURL, binaryName, true)
+		if err != nil {
+			return nil, err
+		}
 	}
 
 	return exec.CommandContext(ctx, binaryPath, args...), nil

internal/oci/pull/tart/tart.go

@@ -3,6 +3,7 @@ package tart
 import (
 	"context"
 	"fmt"
+	"github.com/cirruslabs/vetu/internal/externalbinary/firmware"
 	"github.com/cirruslabs/vetu/internal/oci/annotations"
 	"github.com/cirruslabs/vetu/internal/oci/diskpuller"
 	"github.com/cirruslabs/vetu/internal/oci/mediatypes"
@@ -80,9 +81,14 @@ func PullVMDirectory(
 
 	// Copy latest Hypervisor Firmware since
 	// Tart VM images have no separate kernel
-	fmt.Println("copying EDK2 firmware to use as a kernel...")
+	firmwarePath, firmwareDesc, err := firmware.Firmware(ctx)
+	if err != nil {
+		return err
+	}
+
+	fmt.Printf("copying %s to use as a kernel...\n", firmwareDesc)
 
-	if err := cp.Copy("/usr/share/cloud-hypervisor/CLOUDHV_EFI.fd", vmDir.KernelPath()); err != nil {
+	if err := cp.Copy(firmwarePath, vmDir.KernelPath()); err != nil {
 		return err
 	}
 

scripts/postinstall.sh

@@ -0,0 +1,5 @@
+#!/bin/sh
+
+set -e
+
+/sbin/setcap cap_net_raw,cap_net_admin+eip /usr/bin/vetu