SONiC VS on Apple Silicon

Build and run SONiC Virtual Switch natively on Apple Silicon Macs (M1/M2/M3/M4).

SONiC's official VS (Virtual Switch) image is x86_64-only. This project provides the patches and tooling to build a native ARM64 docker-sonic-vs image and run it for learning, labbing, and development.

Quick Start

Option A: Run the pre-built image

If you already have the built docker-sonic-vs-arm64.gz image:

docker load < docker-sonic-vs-arm64.gz
docker run --privileged --name sonic-vs -d docker-sonic-vs:latest

# Wait ~20 seconds, then:
docker exec -it sonic-vs bash
show interfaces status

Option B: Build from source

See the Apple Silicon Guide for the full build process, or use the automated script:

# 1. Set up the build environment (Colima + Docker CLI)
#    See docs/podman-setup.md for details

# 2. Clone sonic-buildimage
git clone --recurse-submodules https://github.com/sonic-net/sonic-buildimage.git
cd sonic-buildimage

# 3. Apply patches
../scripts/apply-patches.sh

# 4. Build
make configure PLATFORM=vs PLATFORM_ARCH=arm64
make SONIC_BUILD_JOBS=8 INCLUDE_MGMT_FRAMEWORK=n target/docker-sonic-vs.gz

2-Node BGP Lab

# Create management network
docker network create --subnet=172.20.0.0/24 sonic-mgmt

# Start two SONiC nodes
docker run --privileged --name sonic1 --hostname sonic1 \
  --network sonic-mgmt --ip 172.20.0.11 -d docker-sonic-vs:latest
docker run --privileged --name sonic2 --hostname sonic2 \
  --network sonic-mgmt --ip 172.20.0.12 -d docker-sonic-vs:latest

# Wait ~20 seconds, enable BGP, then configure peering
./scripts/configure-bgp-lab.sh

# Check BGP status
docker exec sonic1 vtysh -c "show ip bgp summary"

Or use the lab scripts:

./scripts/lab-up.sh        # Start the lab
./scripts/configure-bgp-lab.sh  # Configure BGP peering
./scripts/verify-lab.sh    # Health check
./scripts/lab-down.sh      # Tear it down

Patches

Seven patches are needed to build SONiC VS for ARM64:

Patch	File	Description
0001	rules/flashrom.mk	Replace hardcoded amd64 with $(CONFIGURED_ARCH)
0002	rules/phy-credo.mk	Gate amd64-only firmware behind arch check
0003	platform/vs/	Add aarch64 libvirt XML definitions
0004	Makefile.work	Fix cross-build mirror arch detection
0005	sonic-slave-*/Dockerfile.j2	Skip cargo-tarpaulin (rustc version mismatch)
0006	src/socat/	Fix dh_installexamples directory conflict
0007	platform/vs/rules.mk	Gate docker-dash-engine on amd64 (no arm64 P4 image)

Patches 0001-0004 are ARM64-specific. Patches 0005-0006 fix general build issues. Patch 0007 gates an x86-only dependency.

Build Environment

The build must run on an ARM64 Linux host. On macOS, use Colima to provide a lightweight Linux VM:

brew install colima docker docker-compose git
colima start --vm-type vz --vz-rosetta --cpu 8 --memory 16 --disk 200 --arch aarch64

See Container Runtime Setup for details.

Requirements:

• Apple Silicon Mac (M1/M2/M3/M4)
• 16GB+ RAM (32GB recommended)
• 150GB+ free disk space
• macOS 13+ (Ventura or later)

Project Structure

scripts/          Lab and build automation scripts
patches/          Build system patches for sonic-buildimage
topologies/       Containerlab topology files
docs/             Guides and build notes

Key Learnings

• SONiC VS platform files (platform/vs/*.mk) already use $(CONFIGURED_ARCH) correctly
• The build system's rules/ directory has a few hardcoded amd64 references
• FRR's bgpd is disabled by default in docker-sonic-vs — must be enabled manually
• VS Ethernet interfaces are virtual (vslib) — BGP must peer over the Docker management network, not SONiC Ethernet IPs
• The SONiC build system uses Docker-in-Docker, which requires a native Linux filesystem (virtiofs from macOS won't work)

Related Issues

• sonic-buildimage#8319 — ARM64 VS build support
• sonic-buildimage#13873 — ARM64 build failures

License

The patches and scripts in this repository are provided under the same license as sonic-buildimage (Apache 2.0).