### Run Just Setup

Source: https://github.com/yanet-platform/yanet2/blob/main/docs/virtual-run.org

Execute the project setup command.

```shell
just setup
```

--------------------------------

### Install Go Protobuf Plugins

Source: https://github.com/yanet-platform/yanet2/blob/main/docs/virtual-run.org

Install protoc-gen-go and protoc-gen-go-grpc using the proxy.

```shell
https_proxy=socks5://127.0.0.1:8080 GOBIN=/usr/local/bin go install google.golang.org/protobuf/cmd/protoc-gen-go@v1.36.11
https_proxy=socks5://127.0.0.1:8080 GOBIN=/usr/local/bin go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@v1.6.1
```

--------------------------------

### Install Ubuntu Mainline Kernel and Prepare Image

Source: https://github.com/yanet-platform/yanet2/blob/main/docs/qemu-run.md

Downloads and installs kernel packages into a mounted image, then extracts the kernel and initrd files for use with QEMU.

```bash
# Download and install kernel
wget https://kernel.ubuntu.com/mainline/v6.14/amd64/linux-image-unsigned-6.14.0-061400-generic_6.14.0-061400.202503241442_amd64.deb
wget https://kernel.ubuntu.com/mainline/v6.14/amd64/linux-modules-6.14.0-061400-generic_6.14.0-061400.202503241442_amd64.deb

sudo cp -v linux-*.deb mnt/
cd mnt
sudo chroot . /usr/bin/bash -c "dpkg -i *deb"

# Copy kernel and initrd
mkdir -p ../shared/kernels
sudo cp -v boot/initrd.img-* boot/vmlinuz-* ../shared/kernels/
sudo chown -cR $USER ../shared/kernels/

# Unmount the image
cd ..
sudo umount mnt
rmdir mnt
```

--------------------------------

### Run development server

Source: https://github.com/yanet-platform/yanet2/blob/main/web/README.md

Start the development server from the repository root.

```bash
npm run dev -w web
```

--------------------------------

### Start BIRD Adapter Server

Source: https://github.com/yanet-platform/yanet2/blob/main/operators/bird-adapter/cmd/yanet-bird-adapter/README.md

Command to start the BIRD adapter server using a specified configuration file.

```bash
yanet-bird-adapter server -c config.yaml
```

--------------------------------

### Install YANET

Source: https://github.com/yanet-platform/yanet2/blob/main/README.md

Install the compiled components using Meson.

```bash
meson install -C build
```

--------------------------------

### Install dependencies

Source: https://github.com/yanet-platform/yanet2/blob/main/web/README.md

Install all dependencies from the repository root using the hoisted node_modules.

```bash
npm install
```

--------------------------------

### Build and Install Yanet CLI

Source: https://github.com/yanet-platform/yanet2/blob/main/docs/virtual-run.org

Compile the project and install the CLI binary.

```shell
make
sudo make cli-install
sudo install -m 755 target/release/yanet-cli /usr/local/bin
```

--------------------------------

### Install Development Packages

Source: https://github.com/yanet-platform/yanet2/blob/main/docs/qemu-run.md

Install essential build tools, dependencies, debugging utilities, Go, and Rust required for YANET development.

```bash
# Update package lists
apt-get update -y

# Install build tools
apt-get install -y \
    meson \
    cmake \
    clang \
    clang-format-19 \
    clang-tidy-19 \
    git \
    just \
    make

# Install development dependencies
apt-get install -y \
    python3-pyelftools \
    libnuma-dev \
    libpcap-dev \
    libyaml-dev \
    protobuf-compiler \
    rustup

# Install debugging tools
apt-get install -y \
    gdb \
    lldb \
    lcov

# Install Go and tools
apt-get install -y golang-go

# Install Go modules
GOBIN=/usr/local/bin go install google.golang.org/protobuf/cmd/protoc-gen-go@v1.36.11
GOBIN=/usr/local/bin go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@v1.6.1

# Install Rust (self update disable need only for rustup installed from apt)
rustup set auto-self-update disable
rustup install stable
```

--------------------------------

### SendPacketAndCapture example in Go

Source: https://github.com/yanet-platform/yanet2/blob/main/tests/functional/README.md

Example of using fw.Run with SendPacketAndCapture to send a packet and capture a response. Requires imports for time and definitions for buildPacket and expectedPacket.

```go
fw.Run("forwards-udp", func(fw *framework.TestFramework, t *testing.T) {
	input := buildPacket()
	output, err := fw.SendPacketAndCapture(0, 0, input, 2*time.Second)
	require.NoError(t, err)
	require.Equal(t, expectedPacket, output)
})
```

--------------------------------

### Install Rustup via Proxy

Source: https://github.com/yanet-platform/yanet2/blob/main/docs/virtual-run.org

Execute the rustup-init script using the SOCKS5 proxy.

```shell
https_proxy=socks5://127.0.0.1:8080 /home/moonug/rustup-init
```

--------------------------------

### Run YANET2 lab quick start commands

Source: https://github.com/yanet-platform/yanet2/blob/main/docs/lab.md

Prepares the functional-test VM image, then runs the lab doctor, up, status, scenario list, scenario run, report, and down commands. Requires Linux x86_64 guest artifacts built with 'make all' and the functional-test image created with 'make -C tests/functional prepare-vm'. The first 'up' can take several minutes; later starts reuse the snapshot.

```bash
make -C tests/functional prepare-vm
just lab doctor
just lab up
just lab status
just lab scenario list
just lab scenario run forward-route
just lab report
just lab down
```

--------------------------------

### Run multiple dev instances

Source: https://github.com/yanet-platform/yanet2/blob/main/web/README.md

Start multiple development servers, each proxying to a different backend.

```bash
# Instance 1
VITE_BACKEND_URL=http://localhost:8081 VITE_DEV_PORT=3000 npm run dev -w web

# Instance 2
VITE_BACKEND_URL=http://localhost:8082 VITE_DEV_PORT=3001 npm run dev -w web
```

--------------------------------

### Install build and development dependencies

Source: https://github.com/yanet-platform/yanet2/blob/main/docs/virtual-run.org

Installs essential build tools, development libraries, debugging utilities, and language-specific tools required for the project.

```shell
apt-get update -y

# Install build tools
apt-get install -y \
    meson \
    clang \
    git \
    make

# Install development dependencies
apt-get install -y \
    software-properties-common \
    python3-pyelftools \
    libnuma-dev \
    libpcap-dev \
    libyaml-dev \
    libibverbs-dev \
    protobuf-compiler

# Install debugging tools
apt-get install -y \
    gdb \
    lldb \
    lcov
# Install tools for 24.04
apt-get install -y \
    clang-format-19 \
    clang-tidy-19 \
    just \
    rustup

# Install Go and tools
apt-get install -y golang-go
# 22.04
add-apt-repository 'deb http://mirror.yandex.ru/mirrors/launchpad/longsleep/golang-backports jammy main' -n
cat <<EOT | sudo apt-key add -
-----BEGIN PGP PUBLIC KEY BLOCK-----

mI0ET551kQEEAME7Iyb7+c79CVWVwe+QaNlAVgauke1Q9Ycw8Rdxj55lKBJ5Ilpp
LwiKreAVin4CCaGEtT9btePbYYKg8I+/dsiDbE9+o8e8FIMEBwy+FS+9bwLZ5WZP
6nEtKPrrk3E+RUUpNbmO6udA62E0q2w7NcoA1jRS2YucsIL39aFXJcmvABEBAAG0
IUxhdW5jaHBhZCBQUEEgZm9yIFNpbW9uIEVpc2VubWFuboi4BBMBAgAiBQJPnnWR
AhsDBgsJCAcDAgYVCAIJCgsEFgIDAQIeAQIXgAAKCRD2vIFzVqPUXle6BAC3FUrE
7j4ltlgGAT2vRNlqWe8W6v0v20e1M8GsFHNB24zL/iRitUMosaWX94ufExwm+83y
ka4Cq0J4oUCSJtgWDLb6K2hYMKLnofj889+4ZN0akNyMOg0O5usD0oJJuRXL0+e3
sZo8b2aj7MwrHe+rTLLnlyKlRTUpt1gGF5GuiA==
=S8ek
-----END PGP PUBLIC KEY BLOCK-----
EOT
sudo apt update
sudo apt install golang-go

# Install Go modules
GOBIN=/usr/local/bin go install google.golang.org/protobuf/cmd/protoc-gen-go@v1.36.11
GOBIN=/usr/local/bin go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@v1.6.1
```

--------------------------------

### Start YANET Dataplane

Source: https://github.com/yanet-platform/yanet2/blob/main/docs/qemu-run.md

Launch the YANET dataplane using the specified configuration file.

```bash
./build/dataplane/yanet-dataplane dataplane.yaml
```

--------------------------------

### Controlplane Filter Build

Source: https://github.com/yanet-platform/yanet2/blob/main/lib/filter/README.md

Example of declaring a signature and initializing a filter with rules.

```c
// signatures (order must match on both sides)
FILTER_COMPILER_DECLARE(my_sig, port_src, net4_dst);

// build rules and compile
struct filter f;
int rc = FILTER_INIT(&f, my_sig, rules, rules_count, &mctx);
assert(rc == 0);
```

--------------------------------

### BIRD Adapter Configuration File

Source: https://github.com/yanet-platform/yanet2/blob/main/operators/bird-adapter/cmd/yanet-bird-adapter/README.md

Example configuration file (config.yaml) defining logging, server address, route operator endpoint, and BIRD socket paths.

```yaml
logging:
  level: info
listen_addr: "localhost:50051"
route_operator_endpoint: "[::1]:8080"
bird:
  name: route0
  sockets:
    - /var/run/bird/yanet-master4.sock
    - /var/run/bird/yanet-master6.sock
  source_v4: "127.0.0.1"
  source_v6: "::1"
```

--------------------------------

### Enable the controlplane instance

Source: https://github.com/yanet-platform/yanet2/blob/main/docs/upgrade.md

Enable and start the default controlplane instance using the new systemd template.

```bash
systemctl enable --now yanet2-controlplane@default
```

--------------------------------

### Configure Rustup

Source: https://github.com/yanet-platform/yanet2/blob/main/docs/virtual-run.org

Disable auto-self-update and install the stable Rust toolchain.

```shell
rustup set auto-self-update disable
rustup install stable
```

--------------------------------

### Run proto lint and breaking checks with make

Source: https://github.com/yanet-platform/yanet2/blob/main/docs/proto-compatibility.md

Run these commands locally to verify proto compatibility. Requires buf to be installed; both targets soft-skip with a warning if buf is absent. make proto-lint also runs a custom Go-based protolint tool that checks go_package alignment. make proto-breaking invokes buf breaking against main.

```bash
# Run buf lint + the custom go_package linter
make proto-lint

# Run buf breaking against main
make proto-breaking
```

--------------------------------

### Start YANET Controlplane

Source: https://github.com/yanet-platform/yanet2/blob/main/docs/qemu-run.md

Launch the YANET controlplane in a separate terminal using the default configuration.

```bash
./build/controlplane/yanet-controlplane -c controlplane/etc/yanet/controlplane.d/default.yaml
```

--------------------------------

### Configure yanet-neighbour-sidecar.yaml

Source: https://github.com/yanet-platform/yanet2/blob/main/operators/neighbour-sidecar/README.md

Example configuration file for the neighbour sidecar, defining server endpoints, gateway connections, and interface mapping.

```yaml
server:
  endpoint: "[::]:9903"
gateways:
  - name: route
    endpoint: "[::1]:50051"
table_name: neighbour-sidecar
default_priority: 100
update_interval: 5m
publish_timeout: 5s
link_map:
  eth1: dpdk0
```

--------------------------------

### Dataplane Filter Query

Source: https://github.com/yanet-platform/yanet2/blob/main/lib/filter/README.md

Example of querying a filter for actions on a packet.

```c
FILTER_QUERY_DECLARE(my_sig, port_src, net4_dst);

uint32_t *actions;
uint32_t count;
FILTER_QUERY(&f, my_sig, &packet, &actions, &count);
// actions points to filter-owned memory
```

--------------------------------

### Add instance_id to gateway, modules, and devices

Source: https://github.com/yanet-platform/yanet2/blob/main/docs/upgrade.md

Example configuration showing the mandatory instance_id field added to the gateway, modules, and devices blocks.

```yaml
gateway:
  instance_id: 0
  server:
    endpoint: "[::1]:8080"
  ...
modules:
  route:
    instance_id: 0
    ...
devices:
  plain:
    instance_id: 0
    ...
```

--------------------------------

### Example YANET Lab Manifest YAML

Source: https://github.com/yanet-platform/yanet2/blob/main/docs/lab.md

A sample manifest file demonstrating the schema structure, including steps and probe definitions. The $schema field points to the validation schema, and steps define command execution with timeouts.

```yaml
$schema: ../../yanet2-lab.schema.json
version: 1
name: example
steps:
  - name: inspect
    argv: [/tmp/yanet/cli/yanet-cli-inspect]
    timeout: 10s
probes:
  - name: packet
    ingress: 0
    egress: 0
    timeout: 1s
    send: {pcap: input.pcap}
    expect: {pcap: expected.pcap}
```

--------------------------------

### Mount Image on macOS

Source: https://github.com/yanet-platform/yanet2/blob/main/docs/qemu-run.md

Mount the image on macOS using ext4fuse. Requires ext4fuse to be installed via Homebrew.

```bash
# Note: ext4fuse must be installed (brew install ext4fuse)
mkdir -p mnt
sudo ext4fuse noble-server-cloudimg-amd64.img mnt -o allow_other
df -h mnt
```

--------------------------------

### cp-lock probe usage commands

Source: https://github.com/yanet-platform/yanet2/blob/main/scripts/uprobe/README.md

Commands to set up, report, and stop the cp-lock probe. Setup requires the CP PID and ptrace permission. Reports can be formatted as Prometheus metrics. Stop clears counters while keeping CP alive.

```sh
sudo yanet-uprobe cp-lock setup --pid "$CP_PID"
sudo yanet-uprobe cp-lock report                    # sorted by total hold time
sudo yanet-uprobe cp-lock report --format prometheus
sudo yanet-uprobe cp-lock stop                      # clear counters, keep CP alive
```

--------------------------------

### Configure and build with Meson

Source: https://github.com/yanet-platform/yanet2/blob/main/README.md

Commands to set up the build directory and compile the core components.

```bash
meson setup build
meson compile -C build
```

--------------------------------

### Launch QEMU with qemu_run.sh

Source: https://github.com/yanet-platform/yanet2/blob/main/docs/qemu-run.md

Executes the universal QEMU launch script with various configuration options for headless mode, GUI, CPU allocation, and kernel versioning.

```bash
# Start in headless mode
./qemu_run.sh noble-server-cloudimg-amd64.img

# Start with GUI
GUI=1 ./qemu_run.sh noble-server-cloudimg-amd64.img

# Override number of CPU cores
SMP=8 ./qemu_run.sh noble-server-cloudimg-amd64.img

# Force specific kernel version
FORCE_VERSION=6.8.0-57-generic ./qemu_run.sh noble-server-cloudimg-amd64.img
```

--------------------------------

### Download Rustup and Just

Source: https://github.com/yanet-platform/yanet2/blob/main/docs/virtual-run.org

Download the required binaries using wget.

```shell
wget https://static.rust-lang.org/rustup/dist/x86_64-unknown-linux-gnu/rustup-init
wget https://github.com/casey/just/releases/download/1.40.0/just-1.40.0-x86_64-unknown-linux-musl.tar.gz
```

--------------------------------

### Prepare image and run functional tests

Source: https://github.com/yanet-platform/yanet2/blob/main/tests/functional/README.md

Commands to build all artifacts, prepare the VM image, and run the functional tests from the repository root. Also checks host tools with check-deps.

```bash
make all
make -C tests/functional prepare-vm
make -C tests/functional test
```

--------------------------------

### framework.SetupHarness

Source: https://github.com/yanet-platform/yanet2/blob/main/tests/functional/README.md

Configures the test harness with options for VM pool, baseline caching, custom YAML, hooks, and more.

```APIDOC
## framework.SetupHarness

### Description
Configures the YANET functional test harness with options for VM pool, baseline caching, custom YAML, hooks, and more.

### Method
SetupHarness

### Parameters
- **PoolName** (string) - Optional - Name used for VM instances and logs.
- **PoolSize** (int) - Optional - Number of VM slots; zero uses YANET_VM_POOL_SIZE.
- **BaselineTag** (string) - Optional - Cache namespace for the baseline snapshot. Required for custom YAML, hooks, or extra fingerprint files.
- **QEMUImage** (string) - Optional - Image path; empty uses YANET_QEMU_IMAGE or the standard test image under tests/functional.
- **ProjectRoot** (string) - Optional - Canonical repository root; empty uses the current project.
- **Dataplane** (string) - Optional - Custom YAML string for dataplane configuration.
- **Controlplane** (string) - Optional - Custom YAML string for controlplane configuration.
- **Forward** (string) - Optional - Custom YAML string for forwarding configuration.
- **Route** (string) - Optional - Custom YAML string for route configuration.
- **Prepare** (function) - Optional - Hook for custom baseline setup.
- **AfterStart** (function) - Optional - Hook for post-start actions.
- **ProfileReady** (function) - Optional - Hook for readiness checks.
- **FingerprintFiles** (list) - Optional - Extra files included in baseline cache invalidation.
- **SkipCommonConfig** (bool) - Optional - Omit standard kni0, forwarding, route, and pipeline setup when test supplies its own.
- **EnableSSHForward** (bool) - Optional - Reserve a host port forwarding to guest SSH for manual debugging.
- **ForceStop** (bool) - Optional - Stop VMs even when YANET_KEEP_VM_ALIVE is set.

### Description
Baseline cache is fingerprinted from the image, generated YAML, binaries, plugins, and configured extra files. Use a distinct BaselineTag when two packages intentionally need different captured guest state.
```

--------------------------------

### Deploy standalone production instance

Source: https://github.com/yanet-platform/yanet2/blob/main/web/README.md

Build the project and prepare the static server directory with a custom config.json.

```bash
npm run build -w web
# Copy dist/ to your static server
# Place a custom config.json at the server root
```

--------------------------------

### Harness.WithBootedVM

Source: https://github.com/yanet-platform/yanet2/blob/main/tests/functional/README.md

Returns a test-scoped framework for the acquired VM.

```APIDOC
## Harness.WithBootedVM

### Description
Returns a test-scoped framework for the acquired VM.

### Method
WithBootedVM

### Parameters
- **vm** (VM) - Required - The booted VM.

### Returns
- A test-scoped framework instance.
```

--------------------------------

### Run YANET in a virtual environment

Source: https://github.com/yanet-platform/yanet2/blob/main/README.md

Commands to manage the QEMU lab environment for local experiments.

```bash
make -C tests/functional prepare-vm
just lab doctor
just lab up
just lab scenario run forward-route
just lab down
```

--------------------------------

### Minimal functional test package with SetupHarness

Source: https://github.com/yanet-platform/yanet2/blob/main/tests/functional/README.md

Go test package using a single Harness with SetupHarness, TestMain, and a test that executes a guest command. Requires calling Harness.Shutdown and the cleanup function.

```go
package functional

import (
	"fmt"
	"os"
	"testing"

	"github.com/stretchr/testify/require"
	"github.com/yanet-platform/yanet2/tests/functional/framework"
)

var harness *framework.Harness

func TestMain(m *testing.M) {
	h, cleanup, err := framework.SetupHarness(framework.HarnessConfig{
		PoolName:    "example",
		BaselineTag: "example",
	})
	if err != nil {
		fmt.Fprintf(os.Stderr, "failed to set up harness: %v\n", err)
		os.Exit(1)
	}
	harness = h
	code := m.Run()
	if err := h.Shutdown(); err != nil {
		fmt.Fprintf(os.Stderr, "failed to shut down harness: %v\n", err)
		code = 1
	}
	cleanup()
	os.Exit(code)
}

func TestExample(t *testing.T) {
	harness.WithBootedVM(t, func(fw *framework.TestFramework) {
		fw.Run("guest-command", func(fw *framework.TestFramework, t *testing.T) {
			output, err := fw.ExecuteCommand("uname -s")
			require.NoError(t, err)
			require.Contains(t, output, "Linux")
		})
	})
}
```

--------------------------------

### Build for production

Source: https://github.com/yanet-platform/yanet2/blob/main/web/README.md

Build the production assets from the repository root.

```bash
npm run build -w web
```

--------------------------------

### Work Directory Structure

Source: https://github.com/yanet-platform/yanet2/blob/main/docs/qemu-run.md

The expected directory layout for the YANET QEMU project.

```bash
./
├── mnt/
├── noble-server-cloudimg-amd64.img
├── qemu_run.sh
├── shared/
└── yanet2/
```

--------------------------------

### Build YANET Project

Source: https://github.com/yanet-platform/yanet2/blob/main/docs/qemu-run.md

Initialize submodules and build the project, controlplane, and CLI components using the 'just' command runner.

```bash
cd /yanet2

# Initialize and update submodules
git submodule update --init --recursive

# Build the project
just setup build

# Build controlplane
just controlplane

# Build cli
just cli
```

--------------------------------

### Build and Test Commands

Source: https://github.com/yanet-platform/yanet2/blob/main/AGENTS.md

Essential commands for initializing, building, testing, and linting the YANET project components.

```bash
git submodule update --init && meson setup build   # once; DPDK is a meson subproject
make all | make dataplane | make cli               # everything | meson compile -C build | cargo build --release --workspace
cd controlplane && go build ./...                  # Go
npm ci && npm run build -w web                     # web is an npm workspace: install at repo root
make setup-debug | make setup-asan                 # debug / ASan+UBSan builds
make test | make test-asan | make test-tsan        # Go + meson tests (cleans go cache first)
make test-functional                               # QEMU VM suite
meson test -C build <name>; go test ./modules/route/...
gofmt -w . ; clang-format -i <file> ; cargo +nightly-2026-08-28 fmt ; cargo clippy
make proto-lint | make lint-go | make lint/clang-syntax | make lint-commit
make proto-go                                      # *.pb.go, needed before go lint locally
make hooks                                         # install git hooks (once per clone)
make fuzz [MODULE=<name>]
make ai/agents                                     # regenerate agent charters from .rulesync/subagents/
```

--------------------------------

### Configure Network Interfaces

Source: https://github.com/yanet-platform/yanet2/blob/main/docs/qemu-run.md

Sets up DHCP for the primary interface and a static IPv6 address for the YANET testing interface.

```bash
cd mnt
sudo chroot . /usr/bin/bash -i <<EOF
# DHCP interface configuration
echo '
[Match]
MACAddress=AABB.CCDD.CAB0
[Network]
DHCP=yes
' |  tee /etc/systemd/network/00-user-net.network

# Static IPv6 configuration
echo '
[Match]
MACAddress=AABB.CCDD.CAB1
[Network]
Address=fd22:6563:20e0:ace2::2/64
Gateway=fd22:6563:20e0:ace2::1
' |  tee /etc/systemd/network/01-static-ip.network

systemctl enable systemd-networkd
EOF
```

--------------------------------

### Run tests

Source: https://github.com/yanet-platform/yanet2/blob/main/README.md

Execute the test suite using Meson.

```bash
meson test -C build
```

--------------------------------

### Configure DPDK Network Interfaces

Source: https://github.com/yanet-platform/yanet2/blob/main/docs/qemu-run.md

Check PCI device status, load the UIO driver, and bind the network interface to the DPDK driver.

```bash
# Check PCI devices status
./subprojects/dpdk/usertools/dpdk-devbind.py --status

# Load driver
modprobe uio_pci_generic

# Bind interface to DPDK driver
./subprojects/dpdk/usertools/dpdk-devbind.py --bind=uio_pci_generic 00:02.0
```

--------------------------------

### Configure dev server proxy and port

Source: https://github.com/yanet-platform/yanet2/blob/main/web/README.md

Run the development server with custom backend URLs or ports using environment variables.

```bash
# Point the dev proxy at a remote gateway
VITE_BACKEND_URL=http://10.0.0.5:8081 npm run dev -w web

# Run a second dev instance on a different port
VITE_BACKEND_URL=http://localhost:8082 VITE_DEV_PORT=3001 npm run dev -w web
```

--------------------------------

### Download and Prepare Ubuntu Cloud Image

Source: https://github.com/yanet-platform/yanet2/blob/main/docs/qemu-run.md

Commands to download, extract, and resize the Ubuntu 24.04 cloud image to 10GB.

```bash
# Download the image
wget https://cloud-images.ubuntu.com/releases/noble/release/ubuntu-24.04-server-cloudimg-amd64.tar.gz

# Extract the image
tar xzf ubuntu-24.04-server-cloudimg-amd64.tar.gz

# Increase image size to 10GB
truncate -s10G noble-server-cloudimg-amd64.img
```

--------------------------------

### fw.RunWith

Source: https://github.com/yanet-platform/yanet2/blob/main/tests/functional/README.md

Restores a named VM snapshot, reconnects the serial console and sockets, then runs the subtest.

```APIDOC
## fw.RunWith

### Description
Restores a named VM snapshot, reconnects the serial console and sockets, then runs the subtest. Use when a subtest needs the exact state captured by that snapshot.

### Method
RunWith

### Parameters
- **snapshot** (string) - Required - The snapshot name.
- **name** (string) - Required - The subtest name.
- **fn** (func) - Required - The function to run.

### Returns
- None.
```

--------------------------------

### Clone the YANET repository

Source: https://github.com/yanet-platform/yanet2/blob/main/README.md

Initial step to download the source code and initialize submodules.

```bash
git clone https://github.com/yanet-platform/yanet2.git
cd yanet2
git submodule update --init
```

--------------------------------

### Set Environment Variables

Source: https://github.com/yanet-platform/yanet2/blob/main/docs/virtual-run.org

Define gateway and IP variables for configuration.

```shell
export DEFGW6=<gw6>
export DEFGW4=<gw4>
export IP6=<ip6>
export IP4=<ip4>
```

--------------------------------

### Build CLI tools

Source: https://github.com/yanet-platform/yanet2/blob/main/README.md

Compile the Rust-based CLI tools using Cargo.

```bash
cargo build --release
```

--------------------------------

### Establish SSH Tunnel

Source: https://github.com/yanet-platform/yanet2/blob/main/docs/virtual-run.org

Create a SOCKS5 proxy tunnel via a bastion host.

```shell
ssh -D 8080 <bastion host>
```

--------------------------------

### Build a filter rule

Source: https://github.com/yanet-platform/yanet2/blob/main/lib/filter/README.md

Construct a filter rule by defining source port ranges and destination networks, then assigning a user action.

```c
// one src port range [1000..2000], one dst net 192.168.0.0/24
struct filter_port_range src_pr = {1000, 2000};
struct net4 dst_net = {.addr = {192,168,0,0}, .mask = {255,255,255,0}};

struct filter_rule r = {0};
r.net4.dst_count = 1;
r.net4.dsts = &dst_net;

r.transport.src_count = 1;
r.transport.srcs = &src_pr;

r.action = 42; // user action (lower 15 bits), terminal by default
```

--------------------------------

### Makefile targets for tests/functional

Source: https://github.com/yanet-platform/yanet2/blob/main/tests/functional/README.md

Commands to check dependencies, prepare the VM, run a test, debug the VM, and clean up. Use from the tests/functional directory.

```bash
make check-deps
make prepare-vm
make test-run TEST=TestFramework
make debug-vm
make clean
```

--------------------------------

### Check and Resize Filesystem on Linux

Source: https://github.com/yanet-platform/yanet2/blob/main/docs/qemu-run.md

Commands to verify and resize the filesystem on the image using e2fsck and resize2fs.

```bash
e2fsck -f noble-server-cloudimg-amd64.img
resize2fs noble-server-cloudimg-amd64.img
```

--------------------------------

### Mount Image on Linux

Source: https://github.com/yanet-platform/yanet2/blob/main/docs/qemu-run.md

Mount the image to the mnt directory on a Linux host.

```bash
mkdir -p mnt
sudo mount noble-server-cloudimg-amd64.img mnt
df -h mnt
```

--------------------------------

### Configure SSH Access

Source: https://github.com/yanet-platform/yanet2/blob/main/docs/qemu-run.md

Sets up SSH authorized keys and regenerates host keys for the cloud image.

```bash
cd mnt
sudo mkdir ./root/.ssh
# Copy your public key
sudo cp ~/.ssh/id_rsa.pub ./root/.ssh/authorized_keys
sudo chmod go-rwx -R ./root/.ssh

# For cloud-image, regenerate host keys
sudo chroot . /usr/bin/bash -c "dpkg-reconfigure openssh-server"
```

--------------------------------

### fw.Run

Source: https://github.com/yanet-platform/yanet2/blob/main/tests/functional/README.md

Creates a Go subtest and resets packet-socket connections before calling the function.

```APIDOC
## fw.Run

### Description
Creates a Go subtest and resets packet-socket connections before calling the function. Use for subtests that build on state left by earlier subtests while keeping each socket stream clean.

### Method
Run

### Parameters
- **name** (string) - Required - The subtest name.
- **fn** (func) - Required - The function to run.

### Returns
- None.
```

--------------------------------

### Move site configuration to the new directory

Source: https://github.com/yanet-platform/yanet2/blob/main/docs/upgrade.md

Relocate the existing controlplane.yaml configuration file to the new controlplane.d directory structure.

```bash
mv /etc/yanet2/controlplane.yaml /etc/yanet2/controlplane.d/default.yaml
```

--------------------------------

### SSH Config Entry

Source: https://github.com/yanet-platform/yanet2/blob/main/docs/qemu-run.md

Recommended SSH configuration for connecting to the QEMU instance.

```ssh-config
Host yanet-dev
    User root
    HostName localhost
    Port 10022
    StrictHostKeyChecking no
```

--------------------------------

### ForTest

Source: https://github.com/yanet-platform/yanet2/blob/main/tests/functional/README.md

Creates a test-scoped framework with the full test name and logger.

```APIDOC
## ForTest

### Description
Creates a test-scoped framework with the full test name and logger.

### Method
ForTest

### Parameters
- **t** (testing.T) - Required - The test object.

### Returns
- A test-scoped framework instance.
```

--------------------------------

### Create rings with yanet-cli-ring create

Source: https://github.com/yanet-platform/yanet2/blob/main/docs/ring.md

Creates a ring with specified capacity and optional publish batch size. Capacity must be a power of two, supporting bytes or IEC units like 1MiB.

```bash
yanet-cli-ring create --name captures --capacity 1MiB
yanet-cli-ring create --name bursts --capacity 1MiB --publish-batch 32
```

--------------------------------

### Tag and push a release commit

Source: https://github.com/yanet-platform/yanet2/blob/main/docs/releasing.md

Commands to fetch tags, create a new version tag at a specific commit, and push the tag to the origin.

```bash
git fetch origin --tags
git tag vX.Y.Z <release-commit-sha>
git push origin refs/tags/vX.Y.Z
```

--------------------------------

### fw.RestoreBooted

Source: https://github.com/yanet-platform/yanet2/blob/main/tests/functional/README.md

Direct restore primitive for the booted template.

```APIDOC
## fw.RestoreBooted

### Description
Direct restore primitive for the booted template.

### Method
RestoreBooted

### Parameters
- None.

### Returns
- None.
```

--------------------------------

### Configure DPDK Hugepages

Source: https://github.com/yanet-platform/yanet2/blob/main/docs/qemu-run.md

Set up 4G of hugepages required for DPDK operation.

```bash
./subprojects/dpdk/usertools/dpdk-hugepages.py --setup 4G
```

--------------------------------

### Reconfigure BIRD Adapter at Runtime

Source: https://github.com/yanet-platform/yanet2/blob/main/operators/bird-adapter/cmd/yanet-bird-adapter/README.md

Command to reconfigure a running server with new BIRD socket paths without requiring a restart.

```bash
yanet-bird-adapter client \
  --server-config config.yaml \
  --config route0 \
  --sockets /var/run/bird/bird.sock,/var/run/bird/bird6.sock
```

--------------------------------

### Inspect YANET Configuration

Source: https://github.com/yanet-platform/yanet2/blob/main/docs/qemu-run.md

Verify YANET operation by inspecting the configuration via the CLI utility.

```bash
# Inspect config
./cli/target/release/yanet-cli inspect
```

--------------------------------

### Harness.Restore

Source: https://github.com/yanet-platform/yanet2/blob/main/tests/functional/README.md

Provides a baseline fast path and a pre-YANET fallback for non-test callers.

```APIDOC
## Harness.Restore

### Description
Provides a baseline fast path and a pre-YANET fallback for non-test callers.

### Method
Restore

### Parameters
- None.

### Returns
- None.
```

--------------------------------

### Provision fwstate-map objects via CLI

Source: https://github.com/yanet-platform/yanet2/blob/main/docs/upgrade.md

Create state tables for IPv4 and IPv6 address families using the yanet-cli-fwstatemap utility. These names are required for subsequent module configuration references.

```bash
yanet-cli-fwstatemap create --name fw4 --kind v4
yanet-cli-fwstatemap create --name fw6 --kind v6
```

--------------------------------

### Runtime configuration config.json

Source: https://github.com/yanet-platform/yanet2/blob/main/web/README.md

Override the default backend and seed additional gateways by placing a config.json file in web/public/.

```json
{
  "defaultBackendUrl": "http://gateway-01:8081",
  "gateways": [
    { "host": "gateway-01", "numa": 0, "addr": "gateway-01:8081" },
    { "host": "gateway-02", "numa": 0, "addr": "gateway-02:8081" }
  ]
}
```

--------------------------------

### Configure ~/.actrc file

Source: https://github.com/yanet-platform/yanet2/blob/main/docs/act.org

Create or update the ~/.actrc file to define custom Docker images for GitHub Actions runners.

```shell
cat ~/.actrc
#-P ubuntu-latest=ghcr.io/catthehacker/ubuntu:full-latest
-P ubuntu-24.04=ghcr.io/catthehacker/ubuntu:act-24.04
```

--------------------------------

### ExecuteCommandsSeparately

Source: https://github.com/yanet-platform/yanet2/blob/main/tests/functional/README.md

Executes multiple commands sequentially, ensuring every command result is needed. This is a framework method for running shell commands inside the guest.

```APIDOC
## ExecuteCommandsSeparately

### Description
Executes multiple commands sequentially, ensuring every command result is needed.

### Method
ExecuteCommandsSeparately(commands...)

### Parameters
- **commands** (string...) - Required - The shell commands to execute in the guest.

### Notes
Commands are executed through the serial console. Host-side arguments should be quoted or passed through manifest argv rules.
```

--------------------------------

### Extract Just Binary

Source: https://github.com/yanet-platform/yanet2/blob/main/docs/virtual-run.org

Extract the just binary to /usr/local/bin.

```shell
tar xf just-1.40.0-x86_64-unknown-linux-musl.tar.gz -C /usr/local/bin/
```

--------------------------------

### Create an annotated release tag

Source: https://github.com/yanet-platform/yanet2/blob/main/docs/releasing.md

Creates an annotated tag using a markdown file for release notes, ensuring markdown headings are preserved with the --cleanup=verbatim flag.

```bash
git tag -a --cleanup=verbatim -F release-notes.md vX.Y.Z <release-commit-sha>
```

--------------------------------

### ExecuteCommands

Source: https://github.com/yanet-platform/yanet2/blob/main/tests/functional/README.md

Executes multiple commands sequentially with fail-fast behavior. If any command fails, execution stops. This is a framework method for running shell commands inside the guest.

```APIDOC
## ExecuteCommands

### Description
Executes multiple commands sequentially with fail-fast behavior. If any command fails, execution stops.

### Method
ExecuteCommands(commands...)

### Parameters
- **commands** (string...) - Required - The shell commands to execute in the guest.

### Notes
Commands are executed through the serial console. Host-side arguments should be quoted or passed through manifest argv rules.
```

--------------------------------

### List rings with yanet-cli-ring list

Source: https://github.com/yanet-platform/yanet2/blob/main/docs/ring.md

Displays a table of all registered rings sorted by name, including their capacity and publish batch settings.

```bash
yanet-cli-ring list
```

--------------------------------

### Configure Cargo Proxy

Source: https://github.com/yanet-platform/yanet2/blob/main/docs/virtual-run.org

Add proxy settings to ~/.cargo/config.toml.

```toml
[http]
proxy = "socks5://127.0.0.1:8080"
```

--------------------------------

### FILTER_INIT(filter, tag, rules, rule_count, ctx)

Source: https://github.com/yanet-platform/yanet2/blob/main/lib/filter/README.md

Compiles rules into the filter using the attribute signature tag. Returns 0 on success, negative on error.

```APIDOC
## FILTER_INIT(filter, tag, rules, rule_count, ctx)

### Description
Compiles rules into the filter using the attribute signature tag. Returns 0 on success, negative on error.

### Parameters
- **filter** (struct filter *) - Required - Pointer to the filter structure to initialize.
- **tag** (signature tag) - Required - Attribute signature tag defining the filter layout.
- **rules** (rules array) - Required - Array of rules to compile.
- **rule_count** (uint32_t) - Required - Number of rules in the rules array.
- **ctx** (struct memory_context *) - Required - Memory context for resource management.

### Returns
- **int** - 0 on success, negative on error.
```

--------------------------------

### Cherry-pick a commit for backporting

Source: https://github.com/yanet-platform/yanet2/blob/main/docs/releasing.md

Use this command to cherry-pick a commit from the main branch onto a release branch before opening a pull request.

```bash
git cherry-pick -x <commit>
```

--------------------------------

### Show ring details with yanet-cli-ring show

Source: https://github.com/yanet-platform/yanet2/blob/main/docs/ring.md

Retrieves the capacity and publish batch configuration for a specific ring identified by name.

```bash
yanet-cli-ring show --name captures
```

--------------------------------

### Initialize filter

Source: https://github.com/yanet-platform/yanet2/blob/main/lib/filter/README.md

Initialize the filter structure using the declared signature and the constructed rule.

```c
struct filter f;
int rc = FILTER_INIT(&f, my_sig, &r, 1, &memory_context);
assert(rc == 0);
```

--------------------------------

### ExecuteCommand

Source: https://github.com/yanet-platform/yanet2/blob/main/tests/functional/README.md

Executes a command in the guest using the default serial command timeout. This is a framework method for running shell commands inside the guest.

```APIDOC
## ExecuteCommand

### Description
Executes a command in the guest using the default serial command timeout.

### Method
ExecuteCommand(command)

### Parameters
- **command** (string) - Required - The shell command to execute in the guest.

### Notes
Commands are executed through the serial console. Host-side arguments should be quoted or passed through manifest argv rules.
```

--------------------------------

### Configure fstab

Source: https://github.com/yanet-platform/yanet2/blob/main/docs/qemu-run.md

Configures the fstab file inside the chroot environment to mount shared directories.

```bash
sudo chroot mnt /bin/bash -c "
echo 'share_fs1 /shared 9p trans=virtio,rw,_netdev,nofail 0 0
yanet2 /yanet2 9p trans=virtio,rw,_netdev,nofail 0 0
' | tee -a /etc/fstab

# Create mount point
mkdir -p /yanet2
"
```

--------------------------------

### Manage Imported Routes via CLI

Source: https://github.com/yanet-platform/yanet2/blob/main/operators/bird-adapter/cmd/yanet-bird-adapter/README.md

Commands to inspect and manage routes imported into the YANET platform using the route CLI.

```bash
# Show imported routes
route show -c route0

# Lookup route
route lookup 10.0.0.1 -c route0

# Sync RIB → FIB
route flush -c route0
```

--------------------------------

### Configure NAT64 script

Source: https://github.com/yanet-platform/yanet2/blob/main/docs/virtual-run.org

A shell script to enable L2/L3 forwarding, configure NAT64 settings, and update pipeline assignments. Ensure the file is executable with chmod +x.

```shell
#!/bin/sh
yanet-cli forward l2-enable --cfg=forward0 --instance 0 --src 0 --dst 1
yanet-cli forward l2-enable --cfg=forward0 --instance 0 --src 1 --dst 0

yanet-cli forward l3-add --cfg=forward0 --instance 0 --src 0 --dst 1 --net $IP4/32
yanet-cli forward l3-add --cfg=forward0 --instance 0 --src 0 --dst 1 --net $IP6/128
yanet-cli forward l3-add --cfg=forward0 --instance 0 --src 0 --dst 1 --net ff02::/16

yanet-cli forward l3-add --cfg=forward0 --instance 0 --src 1 --dst 0 --net 0.0.0.0/0
yanet-cli forward l3-add --cfg=forward0 --instance 0 --src 1 --dst 0 --net ::/0

yanet-cli route insert --cfg route0 --via $DEFGW6 ::/0

yanet-cli nat64 prefix add --cfg nat0 --instance 0 --prefix $NAT64_PREFIX
yanet-cli nat64 mapping add --cfg nat0 --instance 0 --ipv4 <ipv4> --ipv6 <ipv6> --prefix-index 0
yanet-cli nat64 mtu --cfg nat0 --instance 0 --ipv4-mtu 1450 --ipv6-mtu 6950

yanet-cli pipeline update --name=bootstrap --modules forward:forward0 --instance=0
yanet-cli pipeline update --name=nat64 --modules forward:forward0 --modules nat64:nat0 --modules route:route0 --instance=0

yanet-cli pipeline assign --instance=0 --device=1 --pipelines bootstrap:1
yanet-cli pipeline assign --instance=0 --device=0 --pipelines nat64:1
```

--------------------------------

### Build the sidecar container image

Source: https://github.com/yanet-platform/yanet2/blob/main/operators/neighbour-sidecar/README.md

Command to build the Docker image for the neighbour sidecar using the provided Dockerfile.

```sh
docker build -f deploy/yanet-neighbour-sidecar.Dockerfile -t yanet-neighbour-sidecar .
```

--------------------------------

### Configure Git Proxy

Source: https://github.com/yanet-platform/yanet2/blob/main/docs/virtual-run.org

Set the global Git HTTP proxy to the SOCKS5 tunnel.

```shell
git config --global http.proxy 'socks5://127.0.0.1:8080'
```

--------------------------------

### Set NAT64 prefix environment variable

Source: https://github.com/yanet-platform/yanet2/blob/main/docs/virtual-run.org

Export the NAT64 prefix required for configuration.

```shell
export NAT64_PREFIX=<prefix>
```

--------------------------------

### FILTER_INIT

Source: https://github.com/yanet-platform/yanet2/blob/main/lib/filter/README.md

Initializes a filter with a given signature and a set of rules. Returns an integer status code.

```APIDOC
## FILTER_INIT

### Description
Initializes a filter with a given signature and a set of rules. Returns an integer status code.

### Syntax
int FILTER_INIT(struct filter *f, sig, struct filter_rule *rules, size_t rule_count, void *memory_context)

### Parameters
- **f** (struct filter *) - Required - Pointer to the filter structure to initialize.
- **sig** (signature) - Required - The signature declared with FILTER_COMPILER_DECLARE.
- **rules** (struct filter_rule *) - Required - Array of filter rules to compile.
- **rule_count** (size_t) - Required - Number of rules in the array.
- **memory_context** (void *) - Required - Memory context for allocations.

### Return Value
- **int** - 0 on success, non-zero on failure.

### Example
```c
struct filter f;
int rc = FILTER_INIT(&f, my_sig, &r, 1, &memory_context);
assert(rc == 0);
```
```

--------------------------------

### Insert routes via yanet-cli

Source: https://github.com/yanet-platform/yanet2/blob/main/docs/virtual-run.org

Commands to insert default IPv6 and IPv4 routes into the routing configuration.

```shell
sleep 3
yanet-cli route insert --cfg route0 --instance 0 --via $DEFGW6 ::/0
yanet-cli route insert --cfg route0 --instance 0 --via $DEFGW4 0.0.0.0/0
```

--------------------------------

### Run L3b functional test

Source: https://github.com/yanet-platform/yanet2/blob/main/modules/l3b/tests/functional/testdata/056_balancer_vs_ping_reply/README.md

Executes the specific functional test case for the L3b balancer ping reply configuration from the repository root.

```sh
go test -count=1 -v ./modules/l3b/tests/functional -run '^Test_L3b_ConfiguredRealsGateEcho$'
```

--------------------------------

### Clone yanet2 repository

Source: https://github.com/yanet-platform/yanet2/blob/main/docs/virtual-run.org

Use this command to clone the yanet2 project from GitHub.

```shell
git clone git@github.com:yanet-platform/yanet2.git
```

--------------------------------

### Reserve old field numbers and names in a new versioned package

Source: https://github.com/yanet-platform/yanet2/blob/main/docs/proto-compatibility.md

When creating a .v2 package, drop v1 fields and reserve their numbers and names to prevent accidental reuse.

```protobuf
message Foo {
  reserved 3;
  reserved "old_field";
}
```

--------------------------------

### Query filter

Source: https://github.com/yanet-platform/yanet2/blob/main/lib/filter/README.md

Perform a query against the initialized filter to retrieve actions for a given packet.

```c
uint32_t *actions;
uint32_t count;
FILTER_QUERY(&f, my_sig, &packet, &actions, &count);
// actions points into filter-owned memory; do not free
```

--------------------------------

### Run workflows locally with act

Source: https://github.com/yanet-platform/yanet2/blob/main/docs/act.org

Execute GitHub Actions workflows from the repository root using the specified container architecture and artifact server path.

```shell
act --container-architecture linux/amd64 --artifact-server-path ./artifacts
```

--------------------------------

### Run specific job with act

Source: https://github.com/yanet-platform/yanet2/blob/main/docs/act.org

Execute a single job named build-deb using the act command.

```shell
act --container-architecture linux/amd64 --artifact-server-path ./artifacts -j build-deb
```

--------------------------------

### Create a named ring for pdump capture

Source: https://github.com/yanet-platform/yanet2/blob/main/docs/upgrade.md

Create a ring object before creating or updating any pdump configuration that captures into it. The ring must have a capacity of at least 128 KiB per worker.

```bash
yanet-cli-ring create --name captures --capacity 1MiB
```

--------------------------------

### ExecuteCommandWithTimeout

Source: https://github.com/yanet-platform/yanet2/blob/main/tests/functional/README.md

Executes a command in the guest with a bounded custom timeout. This is a framework method for running shell commands inside the guest with a specified timeout.

```APIDOC
## ExecuteCommandWithTimeout

### Description
Executes a command in the guest with a bounded custom timeout.

### Method
ExecuteCommandWithTimeout(command, timeout)

### Parameters
- **command** (string) - Required - The shell command to execute in the guest.
- **timeout** (duration) - Required - The timeout duration for the command execution.

### Notes
Commands are executed through the serial console. Host-side arguments should be quoted or passed through manifest argv rules.
```

--------------------------------

### Meson Controlplane Dependency

Source: https://github.com/yanet-platform/yanet2/blob/main/lib/filter/README.md

Add both include and link dependencies for the controlplane compiler.

```meson
deps += [lib_filter_compiler_dep]
```

--------------------------------

### Set Decap Prefix

Source: https://github.com/yanet-platform/yanet2/blob/main/docs/virtual-run.org

Define the decap prefix environment variable.

```shell
export DECAP_PREFIX=<prefix>
```