vmsan

🔥 مجموعة أدوات حماية Firecracker microVM

أنشئ وأدر واتصل بالـ microVMs المعزولة من Firecracker عبر سطر الأوامر. قم بتشغيل VM محمية في ميلي ثانية، نفذ الأوامر، انقل الملفات — لا حاجة لـ SSH.

📚 اقرأ الوثائق الكاملة على vmsan.dev

✨ الميزات

• ⚡ إقلاع بالميلي ثانية — تبدأ microVMs من Firecracker في أقل من 200 مللي ثانية
• 🔒 عزل أمني — jailer, seccomp, cgroups, ومساحات أسماء شبكة لكل VM
• 🖥️ قشرة تفاعلية — PTY عبر WebSocket مع دعم طرفية كامل
• 📂 نقل الملفات — رفع وتنزيل بدون SSH
• 🐳 صور Docker — بناء rootfs من أي صورة OCI باستخدام --from-image
• 🏃 تنفيذ الأوامر — تشغيل الأوامر مع إخراج متدفق، حقن متغيرات البيئة، و sudo
• 🧩 بيئات تشغيل متعددة — base, node22, node24, python3.13
• 📸 لقطات VM — حفظ واستعادة حالة VM
• 📊 مخرجات JSON — علامة --json للبرمجة النصية والأتمتة

📋 المتطلبات الأساسية

• لينكس (x86_64 أو aarch64) مع دعم KVM
• صلاحيات الجذر/sudo (مطلوبة لتوصيل جهاز TAP و jailer)
• Docker (للتثبيت من المصدر، إعادة بناء بيئات التشغيل محلياً، و --from-image)

🚀 التثبيت

curl -fsSL https://vmsan.dev/install | bash

يقوم هذا بتنزيل وتثبيت كل شيء في ~/.vmsan/:

• Firecracker + Jailer (أحدث إصدار)
• نواة لينكس (vmlinux 6.1)
• rootfs لأوبونتو 24.04 (محولة من squashfs إلى ext4)
• CLI لـ vmsan + الوكيل داخل VM
• صور بيئات التشغيل (node22, node24, python3.13) تُنزل كقطع أثرية مبنية مسبقاً

تثبيتات الإصدار القياسي تقوم بتنزيل بيئات التشغيل المضمنة من https://artifacts.vmsan.dev/ ولا تتطلب Docker. تثبيتات المصدر لا تزال تبني بيئات التشغيل محلياً.

curl -fsSL https://vmsan.dev/install | bash -s -- --uninstall

# Install dependencies
bun install

# Build the in-VM agent
cd agent && make install && cd ..

# Build the CLI
bun run build

# Link local build
mkdir -p ~/.vmsan/bin
ln -sf "$(pwd)/dist/bin/cli.mjs" ~/.vmsan/bin/vmsan

📖 الاستخدام

# Create and start a VM
vmsan create --runtime node22 --memory 512 --cpus 2

# Create a VM from a Docker image
vmsan create --from-image node:22-alpine

# List all VMs
vmsan list

# Execute a command inside a VM
vmsan exec <vm-id> ls -la

# Interactive exec with PTY
vmsan exec -i <vm-id> bash

# Connect to a running VM shell
vmsan connect <vm-id>

# Upload a file to a VM
vmsan upload <vm-id> ./local-file.txt /remote/path/file.txt

# Download a file from a VM
vmsan download <vm-id> /remote/path/file.txt ./local-file.txt

# Snapshot a running VM
vmsan snapshot create <vm-id>

# List snapshots
vmsan snapshot list

# Restore a VM from a snapshot
vmsan create --snapshot <snapshot-id>

# Stop a VM
vmsan stop <vm-id>

# Remove a VM
vmsan remove <vm-id>

الأعلام العالمية

الأوامر

⚠️ القيود المعروفة

• لا يوجد شبكات بين VMs (مخطط للإصدار 0.4.0)
• لا يوجد إعداد تصريحي / vmsan.toml (مخطط للإصدار 0.5.0)
• لا دعم لعدة مضيفين (مخطط للإصدار 0.7.0)
• يستخدم nftables مع تطبيق قاعدة ذري لعزل الشبكة (منذ 0.2.0)
• لا يوجد تصفية DNS أو SNI (مخطط للإصدار 0.3.0)
• ICMP محظور افتراضياً من VMs (يمنع نفق ICMP)
• UDP محظور افتراضياً باستثناء DNS (يمنع تسريب UDP؛ لن يعمل QUIC/HTTP3)
• NTP (UDP 123) محظور — يستخدم kvm-clock لمزامنة الوقت، قد تنحرف VMs طويلة التشغيل
• جدار الحماية للمضيف (ufw/firewalld) قد يحتاج إلى قواعد سماح صريحة لحركة مرور vmsan
• لينكس فقط — يتطلب دعم KVM
• المنصة الرئيسية: أوبونتو 24.04 LTS

🛠️ التطوير

# Build
bun run build

# Link local build
ln -sf "$(pwd)/dist/bin/cli.mjs" ~/.vmsan/bin/vmsan

# Dev mode (watch)
bun run dev

# Run tests
bun run test

# Type check
bun run typecheck

# Lint & format
bun run lint
bun run fmt

🏗️ الهندسة المعمارية

bin/            CLI entry point
src/
  commands/     CLI subcommands
  services/     Firecracker client, agent client, VM service
  lib/          Utilities (jailer, networking, shell, logging)
  errors/       Typed error system
  generated/    Firecracker API type definitions
agent/          Go agent that runs inside the VM
docs/           Documentation site (vmsan.dev)

كيف يعمل

1. vmsan يستخدم Firecracker لإنشاء microVMs خفيفة الوزن مع jailer للعزل الأمني
2. كل VM يحصل على جهاز شبكة TAP مع شبكة فرعية /30 خاصة به (198.19.{slot}.0/30)
3. وكيل مبني على Go يعمل داخل VM، ويعرض واجهة HTTP API لتنفيذ الأوامر وعمليات الملفات والوصول إلى القشرة
4. يتواصل CLI مع الوكيل عبر شبكة المضيف-الضيف

يتم تخزين الحالة في ~/.vmsan/:

~/.vmsan/
  vms/          VM state files (JSON)
  jailer/       Chroot directories
  bin/          Agent binary
  kernels/      VM kernel images
  rootfs/       Base root filesystems
  registry/     Docker image rootfs cache
  snapshots/    VM snapshots

⚖️ مقارنة vmsan مع الآخرين