alice.pds.demo.boltless.dev
This repository has no description
1package microvm
2
3import (
4 "context"
5 "crypto/sha256"
6 _ "embed"
7 "encoding/hex"
8 "encoding/json"
9 "errors"
10 "fmt"
11 "log/slog"
12 "os"
13 "os/exec"
14 "path/filepath"
15 "strconv"
16 "strings"
17 "sync"
18 "time"
19
20 "github.com/digitalocean/go-qemu/qmp"
21 "github.com/google/uuid"
22)
23
24const (
25 defaultQMPTimeout = 10 * time.Second
26 outerSlirpCIDR = "10.0.2.0/24"
27 innerSlirpNet = "10.0.3.0/24"
28 innerSlirpHost = "10.0.3.2"
29 innerSlirpDNS = "10.0.3.3"
30 innerSlirpDHCP = "10.0.3.15"
31 netnsTapName = "tap0"
32 netnsMTU = "65520"
33)
34
35type QEMUConfig struct {
36 Image ImageSpec
37 BootTimeout time.Duration
38 CID uint32
39 EnableKVM bool
40 QEMULogPath string
41 QMPPath string
42 SerialLogPath string
43 WorkDir string
44 VolumePaths map[string]string
45 VolumeBaseName string
46 Cgroup CgroupLimits
47 Dev bool
48}
49
50type QEMUVMHandle struct {
51 cid uint32
52 Process *os.Process
53 qemuLogPath string
54 QMPMon *qmp.SocketMonitor
55 QMPPath string
56 serialLogPath string
57 workDir string
58
59 qmpSocketPath string
60
61 cmd *exec.Cmd
62 done chan struct{}
63 qemuLogFile *os.File
64 cgroup *CgroupHandle
65 slirpCmd *exec.Cmd
66 slirpExit *os.File
67 waitErr error
68 waitErrMu sync.Mutex
69}
70
71type qemuRunner struct{}
72
73func (qemuRunner) Validate(spec ImageSpec, enableKVM bool) error {
74 if _, err := exec.LookPath(spec.RunnerCmd()); err != nil {
75 return fmt.Errorf("required host command %q not found in PATH: %w", spec.RunnerCmd(), err)
76 }
77 if _, err := os.Stat("/dev/vhost-vsock"); err != nil {
78 return fmt.Errorf("microvm requires /dev/vhost-vsock for vhost-vsock-device: %w", err)
79 }
80 if enableKVM {
81 if _, err := os.Stat("/dev/kvm"); err != nil {
82 return fmt.Errorf("microvm KVM was requested but /dev/kvm is not accessible: %w", err)
83 }
84 }
85 if len(spec.NetworkInterfaces) > 0 {
86 if _, err := os.Stat("/dev/net/tun"); err != nil {
87 return fmt.Errorf("microvm slirp4netns networking requires /dev/net/tun: %w", err)
88 }
89 for _, cmd := range []string{"ip", "mount", "slirp4netns", "unshare"} {
90 if _, err := exec.LookPath(cmd); err != nil {
91 return fmt.Errorf("required host command %q not found in PATH: %w", cmd, err)
92 }
93 }
94 }
95 return nil
96}
97
98func (qemuRunner) Start(ctx context.Context, cfg VMConfig, volumePaths map[string]string, logger *slog.Logger) (VMHandle, error) {
99 bootTimeout := cfg.BootTimeout
100 if bootTimeout == 0 {
101 bootTimeout = 10 * time.Second
102 }
103 return StartQEMU(ctx, QEMUConfig{
104 Image: cfg.Image,
105 BootTimeout: bootTimeout,
106 CID: cfg.CID,
107 EnableKVM: cfg.EnableKVM,
108 WorkDir: cfg.WorkDir,
109 VolumePaths: volumePaths,
110 Cgroup: cfg.Cgroup,
111 Dev: cfg.Dev,
112 }, logger)
113}
114
115// we hash the workDir to get a deterministic qmpSock path
116// since they are AF_UNIX sockets, they are bound by a 108 char long path limit...
117func qmpSocketPath(workDir string) string {
118 base := filepath.Dir(workDir)
119 if workDir == "" {
120 base = os.TempDir()
121 }
122 sum := sha256.Sum256([]byte(workDir))
123 return filepath.Join(base, hex.EncodeToString(sum[:8])+".qmp.sock")
124}
125
126func StartQEMU(ctx context.Context, cfg QEMUConfig, logger *slog.Logger) (VMHandle, error) {
127 if logger == nil {
128 logger = slog.Default()
129 }
130
131 workDir := cfg.WorkDir
132
133 handle := &QEMUVMHandle{
134 workDir: workDir,
135 }
136
137 var ok bool
138 defer func() {
139 if !ok {
140 if detail := vmCrashLog(handle); detail != "" {
141 logger.Error("microVM failed to start", "cid", handle.cid, "detail", detail)
142 }
143 _ = handle.Close()
144 }
145 }()
146
147 cid := cfg.CID
148 if cid == 0 {
149 var err error
150 cid, err = AllocateCID()
151 if err != nil {
152 return nil, err
153 }
154 }
155 if cid < minGuestCID {
156 return nil, fmt.Errorf("guest CID must be >= %d", minGuestCID)
157 }
158 handle.cid = cid
159
160 volumePaths := cfg.VolumePaths
161
162 qemuLogPath := cfg.QEMULogPath
163 if qemuLogPath == "" {
164 qemuLogPath = filepath.Join(workDir, "qemu.log")
165 }
166 qemuLogFile, err := createParentedFile(qemuLogPath)
167 if err != nil {
168 return nil, err
169 }
170 handle.qemuLogPath = qemuLogPath
171 handle.qemuLogFile = qemuLogFile
172
173 serialLogPath := cfg.SerialLogPath
174 if serialLogPath == "" {
175 serialLogPath = filepath.Join(workDir, "serial.log")
176 }
177 if err := os.MkdirAll(filepath.Dir(serialLogPath), 0o755); err != nil {
178 return nil, fmt.Errorf("create serial log directory: %w", err)
179 }
180 handle.serialLogPath = serialLogPath
181
182 qmpPath := cfg.QMPPath
183 if qmpPath == "" {
184 qmpPath = qmpSocketPath(workDir)
185 handle.qmpSocketPath = qmpPath
186 }
187 handle.QMPPath = qmpPath
188
189 qemuCmd := cfg.Image.RunnerCmd()
190 qemuBinary, err := exec.LookPath(qemuCmd)
191 if err != nil {
192 return nil, fmt.Errorf("%s command not found in PATH: %w", qemuCmd, err)
193 }
194
195 args, err := qemuArgs(qemuArgsConfig{
196 Image: cfg.Image,
197 CID: cid,
198 EnableKVM: cfg.EnableKVM,
199 QMPPath: qmpPath,
200 SerialLogPath: serialLogPath,
201 VolumePaths: volumePaths,
202 })
203 if err != nil {
204 return nil, err
205 }
206
207 cmd, slirpNet, err := qemuCommand(ctx, qemuBinary, args, cfg.Image, workDir, cfg.Dev)
208 if err != nil {
209 return nil, err
210 }
211 cmd.Env = append(os.Environ(), "TMPDIR="+workDir)
212 cmd.Stdout = qemuLogFile
213 cmd.Stderr = qemuLogFile
214
215 cgroup, err := prepareCgroup(cfg.Cgroup, logger)
216 if err != nil {
217 return nil, err
218 }
219 handle.cgroup = cgroup
220
221 logger.Info("starting qemu microvm", "cid", cid, "workDir", workDir, "serialLog", serialLogPath, "qmp", qmpPath)
222 if err := cmd.Start(); err != nil {
223 return nil, fmt.Errorf("starting qemu: %w", err)
224 }
225 handle.cmd = cmd
226 handle.Process = cmd.Process
227 handle.done = make(chan struct{})
228 go func() {
229 err := cmd.Wait()
230 handle.waitErrMu.Lock()
231 handle.waitErr = err
232 handle.waitErrMu.Unlock()
233 close(handle.done)
234 }()
235
236 if err := cgroup.AddProcess(cmd.Process.Pid, logger); err != nil {
237 return nil, err
238 }
239
240 if slirpNet != nil {
241 handle.slirpCmd, handle.slirpExit, err = slirpNet.Start(ctx, qemuLogFile, logger)
242 if err != nil {
243 return nil, err
244 }
245 if handle.slirpCmd != nil && handle.slirpCmd.Process != nil {
246 if err := cgroup.AddProcess(handle.slirpCmd.Process.Pid, logger); err != nil {
247 return nil, err
248 }
249 }
250 }
251
252 qmpTimeout := cfg.BootTimeout
253 if qmpTimeout == 0 {
254 qmpTimeout = defaultQMPTimeout
255 }
256 if err := handle.waitForQMP(ctx, qmpTimeout); err != nil {
257 return nil, err
258 }
259
260 status, err := handle.QMPQueryStatus()
261 if err != nil {
262 return nil, err
263 }
264 if status != "running" {
265 return nil, fmt.Errorf("qemu guest not running (status: %s)", status)
266 }
267 logger.Info("qemu microvm running", "cid", cid, "status", status)
268
269 ok = true
270 return handle, nil
271}
272
273func (h *QEMUVMHandle) Wait() error {
274 if h == nil || h.done == nil {
275 return nil
276 }
277 <-h.done
278 h.waitErrMu.Lock()
279 defer h.waitErrMu.Unlock()
280 return h.waitErr
281}
282
283func (h *QEMUVMHandle) WaitContext(ctx context.Context) error {
284 if h == nil || h.done == nil {
285 return nil
286 }
287 select {
288 case <-h.done:
289 h.waitErrMu.Lock()
290 defer h.waitErrMu.Unlock()
291 return h.waitErr
292 case <-ctx.Done():
293 return ctx.Err()
294 }
295}
296
297func (h *QEMUVMHandle) Kill() error {
298 if h == nil || h.Process == nil {
299 return nil
300 }
301 return h.Process.Kill()
302}
303
304func (h *QEMUVMHandle) Shutdown(ctx context.Context) error {
305 if h == nil {
306 return nil
307 }
308 if h.QMPMon != nil {
309 if err := h.QMPSystemPowerdown(); err != nil {
310 return err
311 }
312 }
313 if h.done == nil {
314 return nil
315 }
316 select {
317 case <-h.done:
318 return h.Wait()
319 case <-ctx.Done():
320 _ = h.Kill()
321 _ = h.Wait()
322 return ctx.Err()
323 }
324}
325
326func (h *QEMUVMHandle) Close() error {
327 if h == nil {
328 return nil
329 }
330
331 var closeErr error
332 if h.QMPMon != nil {
333 closeErr = errors.Join(closeErr, h.QMPMon.Disconnect())
334 h.QMPMon = nil
335 }
336 if h.Process != nil {
337 _ = h.Process.Kill()
338 _ = h.Wait()
339 }
340 if h.slirpExit != nil {
341 _ = h.slirpExit.Close()
342 h.slirpExit = nil
343 }
344 if h.slirpCmd != nil && h.slirpCmd.Process != nil {
345 _ = h.slirpCmd.Process.Kill()
346 _ = h.slirpCmd.Wait()
347 h.slirpCmd = nil
348 }
349 if h.qemuLogFile != nil {
350 closeErr = errors.Join(closeErr, h.qemuLogFile.Close())
351 h.qemuLogFile = nil
352 }
353 if h.cgroup != nil {
354 closeErr = errors.Join(closeErr, h.cgroup.Close())
355 h.cgroup = nil
356 }
357 if h.qmpSocketPath != "" {
358 if err := os.Remove(h.qmpSocketPath); err != nil && !os.IsNotExist(err) {
359 closeErr = errors.Join(closeErr, err)
360 }
361 h.qmpSocketPath = ""
362 }
363 return closeErr
364}
365
366func (h *QEMUVMHandle) QMPRun(command qmp.Command) ([]byte, error) {
367 if h == nil || h.QMPMon == nil {
368 return nil, fmt.Errorf("qmp monitor is not connected")
369 }
370 data, err := json.Marshal(command)
371 if err != nil {
372 return nil, err
373 }
374 return h.QMPMon.Run(data)
375}
376
377func (h *QEMUVMHandle) QMPQueryStatus() (string, error) {
378 raw, err := h.QMPRun(qmp.Command{Execute: "query-status"})
379 if err != nil {
380 return "", fmt.Errorf("qmp query-status failed: %w", err)
381 }
382
383 var resp struct {
384 Return struct {
385 Status string `json:"status"`
386 } `json:"return"`
387 }
388 if err := json.Unmarshal(raw, &resp); err != nil {
389 return "", fmt.Errorf("qmp query-status parse: %w", err)
390 }
391 return resp.Return.Status, nil
392}
393
394func (h *QEMUVMHandle) QMPSystemPowerdown() error {
395 _, err := h.QMPRun(qmp.Command{Execute: "system_powerdown"})
396 return err
397}
398
399func (h *QEMUVMHandle) Logs() VMLogs {
400 if h == nil {
401 return VMLogs{}
402 }
403 return VMLogs{
404 Serial: h.serialLogPath,
405 Extra: map[string]string{
406 "qemu": h.qemuLogPath,
407 },
408 }
409}
410
411func (h *QEMUVMHandle) CID() uint32 {
412 if h == nil {
413 return 0
414 }
415 return h.cid
416}
417
418func (h *QEMUVMHandle) WorkDir() string {
419 if h == nil {
420 return ""
421 }
422 return h.workDir
423}
424
425func (h *QEMUVMHandle) OOMKilled() bool {
426 if h == nil {
427 return false
428 }
429 return h.cgroup.OOMKilled()
430}
431
432func (h *QEMUVMHandle) waitForQMP(ctx context.Context, timeout time.Duration) error {
433 qmpCtx, cancel := context.WithTimeout(ctx, timeout)
434 defer cancel()
435
436 var lastErr error
437 for {
438 mon, err := qmp.NewSocketMonitor("unix", h.QMPPath, 2*time.Second)
439 if err == nil {
440 if err = mon.Connect(); err == nil {
441 h.QMPMon = mon
442 return nil
443 }
444 _ = mon.Disconnect()
445 }
446 lastErr = err
447
448 select {
449 case <-qmpCtx.Done():
450 return fmt.Errorf("qmp connect timeout: %w", lastErr)
451 case <-h.done:
452 return fmt.Errorf("qemu exited before qmp was ready: %w", h.Wait())
453 case <-time.After(25 * time.Millisecond):
454 }
455 }
456}
457
458func qemuCommand(
459 ctx context.Context,
460 qemuBinary string,
461 args []string,
462 spec ImageSpec,
463 workDir string,
464 dev bool,
465) (*exec.Cmd, *slirpNamespace, error) {
466 if len(spec.NetworkInterfaces) == 0 {
467 return exec.CommandContext(ctx, qemuBinary, args...), nil, nil
468 }
469
470 ipPath, err := exec.LookPath("ip")
471 if err != nil {
472 return nil, nil, fmt.Errorf("ip command not found in PATH: %w", err)
473 }
474 mountPath, err := exec.LookPath("mount")
475 if err != nil {
476 return nil, nil, fmt.Errorf("mount command not found in PATH: %w", err)
477 }
478 unsharePath, err := exec.LookPath("unshare")
479 if err != nil {
480 return nil, nil, fmt.Errorf("unshare command not found in PATH: %w", err)
481 }
482
483 pidFile, resolvPath, wrapperPath, err := prepareQEMUNetnsFiles(workDir, dev)
484 if err != nil {
485 return nil, nil, err
486 }
487
488 cmdArgs := append([]string{
489 "--user",
490 "--map-root-user",
491 "--net",
492 "--mount",
493 "--propagation", "private",
494 "--",
495 wrapperPath,
496 pidFile,
497 ipPath,
498 mountPath,
499 resolvPath,
500 qemuBinary,
501 }, args...)
502
503 cmd := exec.CommandContext(ctx, unsharePath, cmdArgs...)
504
505 return cmd, &slirpNamespace{
506 spec: spec,
507 pidFile: pidFile,
508 dev: dev,
509 }, nil
510}
511
512func prepareQEMUNetnsFiles(workDir string, dev bool) (pidFile, resolvPath, wrapperPath string, err error) {
513 pidFile = filepath.Join(workDir, "qemu-netns.pid")
514 resolvPath = filepath.Join(workDir, "qemu-netns-resolv.conf")
515 wrapperPath = filepath.Join(workDir, "qemu-netns-wrapper")
516
517 // the guest resolves through shuttle on 127.0.0.1. keep qemu's slirp DNS
518 // pointed at an unroutable local resolver inside this network namespace so
519 // direct guest queries to 10.0.3.3 don't bypass the shuttle dns policy.
520 if err := os.WriteFile(resolvPath, []byte("nameserver 127.0.0.1\n"), 0o644); err != nil {
521 return "", "", "", fmt.Errorf("write qemu network namespace resolv.conf: %w", err)
522 }
523
524 if err := writeNetnsWrapper(wrapperPath, dev); err != nil {
525 return "", "", "", fmt.Errorf("write qemu network namespace wrapper: %w", err)
526 }
527
528 return pidFile, resolvPath, wrapperPath, nil
529}
530
531type qemuArgsConfig struct {
532 Image ImageSpec
533 CID uint32
534 EnableKVM bool
535 QMPPath string
536 SerialLogPath string
537 VolumePaths map[string]string
538}
539
540func qemuArgs(cfg qemuArgsConfig) ([]string, error) {
541 uuid := uuid.New()
542
543 b := newArgBuilder(64)
544
545 addQEMUMachineArgs(&b, cfg, uuid)
546 addQEMUStoreArgs(&b, cfg)
547
548 if cfg.EnableKVM {
549 addQEMUKVMArgs(&b, cfg.Image)
550 }
551
552 if err := addQEMUVolumeArgs(&b, cfg); err != nil {
553 return nil, err
554 }
555
556 if err := addQEMUNetworkArgs(&b, cfg.Image.NetworkInterfaces); err != nil {
557 return nil, err
558 }
559
560 b.Optf("-device", "vhost-vsock-device,guest-cid=%d", cfg.CID)
561
562 if len(cfg.Image.RunnerConfig.ExtraArgs) > 0 {
563 b.Add(cfg.Image.RunnerConfig.ExtraArgs...)
564 }
565
566 return b.Args(), nil
567}
568
569func addQEMUMachineArgs(b *argBuilder, cfg qemuArgsConfig, uuid uuid.UUID) {
570 if cfg.Image.RunnerConfig.Machine != "" {
571 b.Opt("-M", cfg.Image.RunnerConfig.Machine)
572 }
573 b.Optf("-m", "%dM", cfg.Image.MemoryMiB)
574 b.Opt("-smp", strconv.Itoa(cfg.Image.VCPUs))
575
576 b.Add(
577 "-nodefaults",
578 "-no-user-config",
579 "-no-reboot",
580 )
581
582 b.Opt("-kernel", cfg.Image.Kernel)
583 b.Opt("-initrd", cfg.Image.Initrd)
584
585 b.Opt("-device", "virtio-rng-device")
586
587 b.Optf("-smbios", "type=1,uuid=%s", uuid)
588 b.Opt("-serial", "file:"+cfg.SerialLogPath)
589
590 // use virtio console if requsted. this is faster than the serial UART logging
591 // because serial has a higher cost when being accesssed. we still have to
592 // support serial itself for early kernel boot but thats OK.
593 if cfg.Image.RunnerConfig.Console == "hvc0" {
594 b.Optf("-chardev", "file,id=virtiocon0,path=%s,append=on", cfg.SerialLogPath)
595 b.Add("-device", "virtio-serial-device")
596 b.Opt("-device", "virtconsole,chardev=virtiocon0")
597 }
598 b.Opt("-display", "none")
599 b.Opt("-monitor", "none")
600 b.Opt("-append", cfg.Image.BootArgs)
601
602 b.Opt("-sandbox", "on")
603 b.Optf("-qmp", "unix:%s,server,nowait", cfg.QMPPath)
604}
605
606func addQEMUStoreArgs(b *argBuilder, cfg qemuArgsConfig) {
607 drive := newOptionBuilder(8)
608 drive.KV("id", "store")
609 drive.KV("format", "raw")
610 drive.Add("read-only=on")
611 drive.KV("file", cfg.Image.StoreDisk)
612 drive.Add("if=none")
613 drive.Add("aio=io_uring")
614
615 b.Opt("-drive", drive.String())
616 b.Opt("-device", "virtio-blk-device,drive=store")
617}
618
619func addQEMUKVMArgs(b *argBuilder, image ImageSpec) {
620 b.Flag("-enable-kvm")
621 if image.RunnerConfig.CPU != "" {
622 b.Opt("-cpu", image.RunnerConfig.CPU)
623 }
624 b.Opt("-device", "i8042")
625}
626
627func addQEMUVolumeArgs(b *argBuilder, cfg qemuArgsConfig) error {
628 for index, volume := range cfg.Image.Volumes {
629 path := cfg.VolumePaths[volume.Image]
630 if path == "" {
631 return fmt.Errorf("missing prepared path for volume %q", volume.Image)
632 }
633
634 driveID := fmt.Sprintf("volume%d", index)
635
636 drive := newOptionBuilder(10)
637 drive.KV("id", driveID)
638 drive.KV("format", "raw")
639 drive.Add("read-only=off")
640 drive.KV("file", path)
641 drive.Add("if=none")
642 drive.Add("aio=io_uring")
643 drive.Add("discard=unmap")
644 drive.Add("cache=none")
645
646 b.Opt("-drive", drive.String())
647 b.Optf("-device", "virtio-blk-device,drive=%s", driveID)
648 }
649
650 return nil
651}
652
653func addQEMUNetworkArgs(b *argBuilder, interfaces []NetworkInterface) error {
654 for _, networkInterface := range interfaces {
655 if networkInterface.Type != "slirp4netns" {
656 return fmt.Errorf("unsupported microvm network interface type %q", networkInterface.Type)
657 }
658
659 netdevOpts := newOptionBuilder(6)
660 netdevOpts.Add("user")
661 netdevOpts.KV("id", networkInterface.ID)
662 netdevOpts.KV("net", innerSlirpNet)
663 netdevOpts.KV("host", innerSlirpHost)
664 netdevOpts.KV("dns", innerSlirpDNS)
665 netdevOpts.KV("dhcpstart", innerSlirpDHCP)
666
667 b.Opt("-netdev", netdevOpts.String())
668 b.Optf(
669 "-device", "virtio-net-device,netdev=%s,mac=%s",
670 networkInterface.ID, networkInterface.MAC,
671 )
672 }
673
674 return nil
675}
676
677func waitForPIDFile(ctx context.Context, path string) (string, error) {
678 waitCtx, cancel := context.WithTimeout(ctx, 5*time.Second)
679 defer cancel()
680
681 ticker := time.NewTicker(25 * time.Millisecond)
682 defer ticker.Stop()
683
684 for {
685 data, err := os.ReadFile(path)
686 if err == nil {
687 pid := strings.TrimSpace(string(data))
688 if pid != "" {
689 return pid, nil
690 }
691 } else if !errors.Is(err, os.ErrNotExist) {
692 return "", fmt.Errorf("read qemu network namespace pid: %w", err)
693 }
694
695 select {
696 case <-waitCtx.Done():
697 return "", fmt.Errorf("waiting for qemu network namespace pid: %w", waitCtx.Err())
698 case <-ticker.C:
699 }
700 }
701}