builder: vagrant: introduce Vagrantfile

The contributor can make use of a VM box (arm64/amd64) using the
following Makefile rules: vagrant-up, vagrant-ssh, vagrant-halt and
vagrant-destroy.

One can override the ARCH env var:
make vagrant-up ARCH=arm64

Whether the override will work depends on the availability of online
boxes and compatibility of architecture and providers (vbox, parallels).

Documentation added.

Tested in Darwin (M1) and Linux (amd64).

.gitignore

@@ -5,4 +5,5 @@ selftest/*/*-static
 selftest/*/*-dynamic
 selftest/uprobe/ctest
 selftest/uprobe/gotest
-testing/tracee
+testing/tracee
+.vagrant*

Makefile

@@ -7,8 +7,10 @@ HELPERS = ./helpers
 CC = gcc
 CLANG = clang
 GO = go
+VAGRANT = vagrant
 
-ARCH := $(shell uname -m | sed 's/x86_64/amd64/g; s/aarch64/arm64/g')
+HOSTOS = $(shell uname)
+ARCH ?= $(shell uname -m | sed 's/x86_64/amd64/g; s/aarch64/arm64/g')
 
 BTFFILE = /sys/kernel/btf/vmlinux
 BPFTOOL = $(shell which bpftool || /bin/false)
@@ -180,6 +182,26 @@ helpers-test-static-run: libbpfgo-static
 helpers-test-dynamic-run: libbpfgo-dynamic
 	sudo $(GO) test -v $(HELPERS)/...
 
+# vagrant
+
+VAGRANT_DIR = $(abspath ./builder)
+
+.PHONY: vagrant-up
+.PHONY: vagrant-destroy
+.PHONY: vagrant-halt
+.PHONY: vagrant-ssh
+
+vagrant-up: .vagrant-up
+vagrant-destroy: .vagrant-destroy
+vagrant-halt: .vagrant-halt
+vagrant-ssh: .vagrant-ssh
+
+.vagrant-%:
+	VAGRANT_VAGRANTFILE=$(VAGRANT_DIR)/Vagrantfile-ubuntu \
+		ARCH=$(ARCH) \
+		HOSTOS=$(HOSTOS) \
+		$(VAGRANT) $*
+
 # output
 
 $(OUTPUT):

Readme.md

@@ -114,6 +114,20 @@ libbpfgo does not yet have a regular schedule for cutting releases. There has no
 
 *Note*: some distributions might have local changes to their libbpf package and their version might include backports and/or fixes differently than upstream versions. In those cases we recommend that libbpfgo is used statically compiled.
 
+## Contributing
+
+To better receive you, libbpfgo makes available GNU Makefile rules for vagrant machines (amd64/arm64) that can be used to compile and test on Linux and Darwin hosts:
+
+| Makefile Rule     | Description                                         |
+|-------------------|-----------------------------------------------------|
+| vagrant-up        | starts and provisions the vagrant environment       |
+| vagrant-ssh       | connects to machine via SSH                         |
+| vagrant-halt      | stops the vagrant machine                           |
+| vagrant-destroy   | stops and deletes all traces of the vagrant machine |
+
+Once connected to the vagrant box you are ready to [build](#building) libbpfgo (e.g. `make libbpfgo-static`).
+
+For further information, check [Vagrantfile.md](./docs/Vagrantfile.md).
 
 ## Learn more
 

builder/Vagrantfile-ubuntu

@@ -0,0 +1,70 @@
+ARCH = ENV["ARCH"] || "amd64"
+HOSTOS = ENV["HOSTOS"] || "undefined"
+
+if ! %w(amd64 arm64).include?(ARCH) then
+    puts "ERROR: ARCH #{ARCH} not supported"
+    abort
+end
+
+if ! %w(Linux Darwin).include?(HOSTOS) then
+    puts "ERROR: HOSTOS #{HOSTOS} not supported"
+    abort
+end
+
+VM_NAME = "libbpfgo-#{ARCH}-vm"
+VM_SOURCE = "/vagrant"
+
+Vagrant.configure("2") do |config|
+  case ARCH
+  when "amd64"
+    config.vm.box = "generic/ubuntu2204"
+  when "arm64"
+    # unique 22.04 arm64 box available to date
+    # sha256sum c209ab013280d3cd26a344def60b7b19fbb427de904ea285057d94ca6ac82dd5
+    # - http://old-releases.ubuntu.com/releases/jammy/SHA256SUMS
+    # - http://old-releases.ubuntu.com/releases/jammy/ubuntu-22.04-live-server-arm64.iso
+    # - https://gitlab.com/jnh3/m1-baseboxes/-/blob/main/ubuntu/ubuntu-22.04-arm64.pkr.hcl#L11-16
+    config.vm.box = "jharoian3/ubuntu-22.04-arm64"
+  end
+
+  config.vm.hostname = VM_NAME
+  config.vm.synced_folder "./", "#{VM_SOURCE}"
+
+  case HOSTOS
+  when "Linux"
+    config.vm.provider "virtualbox" do |vb|
+      vb.name = VM_NAME
+      vb.cpus = "4"
+      vb.memory = "2048"
+    end
+  when "Darwin"
+    config.vm.provider "parallels" do |prl|
+      prl.name = VM_NAME
+    end
+  end
+
+  setup_ssh(config)
+
+  config.vm.provision :shell, inline: "echo INFO: Starting Provision"
+
+  config.vm.provision :shell, inline: "ARCH=#{ARCH} #{VM_SOURCE}/builder/prepare-ubuntu.sh"
+
+  config.vm.provision :shell, inline: "echo INFO: Provision finished, now connect via ssh"
+end
+
+def setup_ssh(config)
+  config.ssh.extra_args = ["-t", "cd #{VM_SOURCE}; bash --login"]
+
+  # workaround for ubuntu 22.04 disabled ssh-rsa support
+  # - https://it-jog.com/khow/vag/vaguperror-ubuntu2204
+  if ARGV[0] == "up" then
+    config.ssh.insert_key = false
+    config.ssh.private_key_path = nil
+    config.ssh.username = "vagrant"
+    config.ssh.password = "vagrant"
+  end
+  config.vm.provision "shell", inline: <<-SHELL
+     sudo echo PubkeyAcceptedAlgorithms +ssh-rsa >> /etc/ssh/sshd_config
+     sudo sudo systemctl restart sshd
+  SHELL
+end

builder/prepare-ubuntu.sh

@@ -0,0 +1,90 @@
+#!/bin/bash
+
+#
+# This shell script is meant to prepare a building/exec environment for libbpfgo.
+#
+
+
+# variables
+
+[ -z "${GO_VERSION}" ] && GO_VERSION="1.17"
+[ -z "${CLANG_VERSION}" ] && CLANG_VERSION="12"
+[ -z "${ARCH}" ] && ARCH="amd64"
+
+
+# functions
+
+die() {
+    echo "ERROR: ${*}"
+    exit 1
+}
+
+info() {
+    echo "INFO: ${*}"
+}
+
+check_tooling() {
+    local tools="sudo apt-get"
+    for tool in ${tools}
+    do
+        command -v "${tool}" >/dev/null 2>&1 || die "missing required tool ${tool}"
+    done
+}
+
+install_pkgs() {
+    # silence 'dpkg-preconfigure: unable to re-open stdin: No such file or directory'
+    export DEBIAN_FRONTEND=noninteractive
+
+    sudo -E apt-get update || die "coud not update package list"
+    for pkg in "${@}"
+    do
+        info "Installing ${pkg}"
+        sudo -E apt-get install -y "${pkg}" || die "could not install ${pkg}"
+        info "${pkg} installed"
+    done
+}
+
+setup_go() {
+    info "Setting Go ${GO_VERSION} as default"
+
+    local tools="go gofmt"
+    for tool in ${tools}
+    do
+        sudo -E update-alternatives --install "/usr/bin/${tool}" "${tool}" "/usr/lib/go-${GO_VERSION}/bin/${tool}" 100
+    done
+
+    info "Go ${GO_VERSION} set as default"
+}
+
+setup_clang() {
+    info "Setting Clang ${CLANG_VERSION} as default"
+
+    local tools="clang llc llvm-strip clang-format"
+    for tool in ${tools}
+    do
+        sudo -E update-alternatives --install "/usr/bin/${tool}" "${tool}" "/usr/bin/${tool}-${CLANG_VERSION}" 100
+    done
+
+    info "Clang ${CLANG_VERSION} set as default"
+}
+
+
+# startup
+
+info "Starting preparation"
+
+check_tooling
+
+install_pkgs \
+    coreutils bsdutils findutils \
+    build-essential pkgconf \
+    golang-"${GO_VERSION}"-go \
+    llvm-"${CLANG_VERSION}" clang-"${CLANG_VERSION}" clang-format-"${CLANG_VERSION}" \
+    linux-headers-generic \
+    linux-tools-generic linux-tools-"$(uname -r)" \
+    zlib1g-dev libelf-dev libbpf-dev
+
+setup_go
+setup_clang
+
+info "Preparation finished"

docs/Vagrantfile.md

@@ -0,0 +1,45 @@
+# Vagrantfile
+
+## Boxes
+
+Currently there are two boxes available in [Vagrantfile-ubuntu](./../builder/Vagrantfile-ubuntu):
+
+| Box                                                                                          | Providers                |
+|----------------------------------------------------------------------------------------------|--------------------------|
+| [generic/ubuntu2204](https://app.vagrantup.com/generic/boxes/ubuntu2204) (amd64)             | virtualbox, parallels    |
+| [jharoian3/ubuntu-22.04-arm64](https://app.vagrantup.com/jharoian3/boxes/ubuntu-22.04-arm64) | parallels                |
+
+It is recommended to use them through the respective [Makefile rules](../Readme.md#contributing) as they are or overriding the `ARCH` environment variable if your architecture and provider allow such virtualization. E.g.: `make vagrant-up ARCH=amd64`.
+
+## Requirements
+
+### Linux
+
+Install them as per your flavour.
+
+- Vagrant
+- VirtualBox
+
+### Darwin
+
+- Vagrant
+
+```shell
+brew install vagrant
+```
+
+- Parallels
+
+```shell
+brew install --cask parallels
+vagrant plugin install vagrant-parallels
+```
+
+## More information
+
+For further information check:
+
+- [Vagrant Documentation](https://www.vagrantup.com/docs)
+- [Vagrant Boxes](https://app.vagrantup.com/boxes/search)
+- [VirtualBox Documentation](https://www.virtualbox.org/wiki/Documentation)
+- [Parallels](https://www.parallels.com)