Docs / CLI

文档 / CLI

CLI reference

CLI 参考

Every option, grouped by what it controls. Examples use anyvm; python3 anyvm.py takes exactly the same arguments. anyvm --help prints the built-in version of this.

全部选项，按管什么分组。例子里写的是 anyvm； python3 anyvm.py 接受完全一样的参数。anyvm --help 会打印内置的这份说明。

Target

目标

--os <name>

The guest operating system. This is the only required option. One of freebsd, ghostbsd, openbsd, netbsd, dragonflybsd, midnightbsd, nextbsd, solaris, omnios, openindiana, tribblix, haiku, ubuntu, openeuler, blissos, hurd, plan9.

$ anyvm --os freebsd

要跑哪个客户机系统。这是唯一必填的选项。可选：freebsd、ghostbsd、openbsd、netbsd、dragonflybsd、midnightbsd、nextbsd、solaris、omnios、openindiana、tribblix、haiku、ubuntu、openeuler、blissos、hurd、plan9。

--release <ver>

Which release to boot. Omit it and AnyVM picks an available one. Matched case-insensitively, so 24.03-lts-sp4 finds OpenEuler's 24.03-LTS-SP4; the published spelling is used from then on. Desktop variants are releases too -- 15.1-kde6, 7.9-xfce.

$ anyvm --os freebsd --release 14.4
$ anyvm --os openbsd --release 7.9-xfce

启动哪个版本。不写的话 AnyVM 自己挑一个可用的。匹配不区分大小写，所以 24.03-lts-sp4 能找到 OpenEuler 的 24.03-LTS-SP4，之后一律按官方写法显示。桌面版也算版本 —— 15.1-kde6、7.9-xfce。

--arch <arch>

Guest CPU architecture: x86_64, aarch64, riscv64, s390x, powerpc64, ppc64le, sparc64, loongarch64, i386. Availability varies per guest -- see guest notes.

$ anyvm --os netbsd --release 11.0 --arch sparc64

客户机 CPU 架构：x86_64、aarch64、riscv64、s390x、powerpc64、ppc64le、sparc64、loongarch64、i386。每个系统支持哪些不一样，见系统说明。

Resources

资源

--mem <MB>

Memory in megabytes. Defaults to 4096 when the host has more than 4 GB of RAM, otherwise 2048.

$ anyvm --os freebsd --mem 8192

内存大小，单位 MB。宿主内存超过 4 GB 时默认 4096，否则 2048。

--cpu <num>

vCPU count. Defaults to the host core count, capped at 8 with hardware acceleration and at 2 under TCG. Pass it explicitly to go higher.

$ anyvm --os freebsd --cpu 4

vCPU 数量。默认取宿主核心数，有硬件加速时封顶 8，TCG 下封顶 2。想要更多就显式写。

--cpu-type <type>

The QEMU CPU model, when the automatic choice is wrong for you.

$ anyvm --os openbsd --arch aarch64 --cpu-type cortex-a72

QEMU 的 CPU 型号，用在自动选的那个不合适的时候。

Images and storage

镜像和存储

--builder <ver>

Pin a specific builder version, so you get the images from that release rather than the newest.

$ anyvm --os netbsd --builder 2.0.1

锁定某个 builder 版本，这样拿到的是那一次发布的镜像，而不是最新的。

--qcow2 <path>

Boot a local qcow2 image and skip downloading entirely.

$ anyvm --os freebsd --qcow2 ./output/freebsd/freebsd-14.4.qcow2

直接启动本地的 qcow2 镜像，完全跳过下载。

--snapshot

QEMU snapshot mode: disk writes are discarded on shutdown. Combined with a cache directory it can run straight from the cache without copying.

$ anyvm --os freebsd --snapshot

QEMU 快照模式：关机时丢弃所有磁盘写入。配合缓存目录，可以直接从缓存里跑，不用先复制一份。

--data-dir <dir>

Where images and caches are stored. Defaults to ./output.

$ anyvm --os freebsd --data-dir /var/lib/anyvm

镜像和缓存放在哪。默认 ./output。

Networking

网络

Networking is QEMU user-mode (slirp). Forwards bind to 127.0.0.1 unless you ask otherwise.

网络走的是 QEMU 用户态（slirp）。除非你另外指定，转发都绑在 127.0.0.1 上。

-p <mapping>

Forward a host port to a guest port. Repeatable. Three forms: host:guest (TCP), tcp:host:guest, udp:host:guest.

$ anyvm --os ubuntu -p 8080:80
$ anyvm --os ubuntu -p tcp:8443:443 -p udp:5353:5353

把宿主端口转发到客户机端口，可以写多次。三种写法：host:guest（TCP）、tcp:host:guest、udp:host:guest。

--ssh-port <port>

Host port forwarded to the guest's SSH. Auto-picked from the free ports if omitted. --sshport is accepted as an alias.

$ anyvm --os freebsd --ssh-port 10022

转发到客户机 SSH 的宿主端口。不写就从空闲端口里自动挑一个。--sshport 是它的别名。

--ssh-name <name>

Add an SSH alias for the guest, so you can reach it as ssh <name> from another terminal.

$ anyvm --os freebsd --ssh-name myvm

给客户机加一个 SSH 别名，这样在别的终端里可以直接 ssh <name>。

--host-ssh-port <port>

The host's own SSH port as reachable from inside the guest, used to generate a Host host entry there. Defaults to 22.

从客户机里能连回来的宿主 SSH 端口，用来在客户机里生成 Host host 那条配置。默认 22。

--public

Bind forwarded ports on 0.0.0.0 instead of loopback, so other machines can reach them.

$ anyvm --os ubuntu --public -p 8080:80

把转发端口绑到 0.0.0.0 而不是回环地址，这样别的机器也连得上。

--enable-ipv6

Turn IPv6 on in QEMU user networking. It is off by default.

在 QEMU 用户态网络里打开 IPv6。默认是关的。

Shared directories

共享目录

-v <host:guest>

Share a host directory with the guest. Repeatable.

$ anyvm --os freebsd -v "$PWD:/data"
$ anyvm --os freebsd -v D:\data:/data

把宿主的一个目录共享给客户机，可以写多次。

--sync <mode>

Which mechanism backs -v. Strictly validated -- an unrecognised value is an error, not a fallback. rsync (default), sshfs, nfs, sys-nfs, scp, 9p.

-v 底下用什么机制。严格校验 —— 值不认识就直接报错，不会悄悄退回默认。可选 rsync（默认）、sshfs、nfs、sys-nfs、scp、9p。

nfs runs the bundled user-space NFS server (nfsd, a single pure Python file downloaded on demand, serving NFSv3 and v4 plus a portmapper). No kernel nfsd and no root, on any host. mynfs is accepted as an alias.

nfs 跑的是自带的用户态 NFS 服务器（nfsd，一个纯 Python 单文件，按需下载，提供 NFSv3、v4 和一个 portmapper）。不用内核 nfsd，不用 root，什么宿主都能跑。mynfs 也是它的别名。

sys-nfs forces the host's kernel NFS server instead. Linux host with root, and the kernel NFS server installed.

sys-nfs 强制改用宿主的内核 NFS 服务器。需要 Linux 宿主、root 权限，并且装了内核 NFS 服务。

9p is Plan 9's backend and its default there; it needs a Linux host.

$ anyvm --os solaris --sync scp -v D:\data:/data
$ anyvm --os freebsd --sync nfs -v "$PWD:/data"
$ anyvm --os plan9 --sync 9p -v "$PWD:/usr/glenda/work"

9p 是 Plan 9 的后端，也是它那里的默认值；需要 Linux 宿主。

Console and display

控制台和显示

--console, -c

Run in the foreground, attached to the guest console.

前台运行，直接连着客户机控制台。

--detach, -d

Run in the background and do not enter SSH.

后台运行，不自动进 SSH。

--serial <port>

Expose the guest serial console on a host TCP port. Auto-selected from 7000 upward if omitted.

把客户机的串口控制台开到宿主的某个 TCP 端口上。不写就从 7000 往上自动选。

--vnc <display>

Enable VNC on a specific display number (0 means :0, port 5900). The VNC web UI is on by default from port 6080 upward regardless; --vnc off disables the whole thing.

$ anyvm --os freebsd --vnc off

在指定显示号上启用 VNC（0 表示 :0，端口 5900）。不管这个选项，VNC 网页控制台默认都从 6080 往上开；--vnc off 把整套关掉。

--vnc-password <pwd>

Require a password for the VNC web UI. On the login page the username can be anything; only the password is checked.

给 VNC 网页控制台设密码。登录页上用户名随便填，只校验密码。

--remote-vnc [<service>]

Put the VNC web UI behind a public tunnel via Cloudflare, Localhost.run, Pinggy or Serveo. Name one with cf, lhr, pinggy or serveo; use no to disable it where it is on by default, as in Google Cloud Shell.

$ anyvm --os openbsd --release 7.9-xfce --remote-vnc cf

通过 Cloudflare、Localhost.run、Pinggy 或 Serveo，把 VNC 网页控制台放到公网隧道后面。用 cf、lhr、pinggy、serveo 指定某一家；在默认开启的环境里（比如 Google Cloud Shell）用 no 关掉。

--mon <port>

Expose the QEMU monitor over telnet on localhost.

在 localhost 上通过 telnet 暴露 QEMU monitor。

--debug

Verbose logging. The first thing to reach for when a boot misbehaves.

详细日志。启动出问题时第一个该用的东西。

Boot and platform

启动和平台

--uefi

Boot via UEFI. FreeBSD enables this implicitly.

用 UEFI 启动。FreeBSD 会隐式打开。

--disktype <type>

Disk interface, for example virtio or ide.

$ anyvm --os dragonflybsd --disktype ide

磁盘接口类型，比如 virtio 或 ide。

--boot-timeout-sec <n>

How long to wait before QEMU is killed and the boot retried once. Default 600. Raised automatically to 1200 for OpenBSD on aarch64, and to 1800 whenever no hardware acceleration is available -- TCG is 10-50x slower, and heavy guests need the room. An explicit value always wins over both.

$ anyvm --os openbsd --arch aarch64 --boot-timeout-sec 1800

等多久之后杀掉 QEMU 并重试一次。默认 600 秒。OpenBSD 的 aarch64 自动提到 1200，没有硬件加速时自动提到 1800 —— TCG 慢 10 到 50 倍，重的系统需要这个余量。你自己写的值永远盖过这两者。

--enable-pmu

Expose the host performance monitoring unit to the guest. Off by default: passing PMU MSRs through -cpu host triggers intermittent general-protection faults during early boot on some host CPU generations, DragonFly BSD worst of all. Turn it on if you need perf, pmcstat or a profiler inside the VM. Only affects x86_64 with hardware acceleration.

$ anyvm --os ubuntu --enable-pmu -- perf stat ls

把宿主的性能监控单元暴露给客户机。默认关闭：通过 -cpu host 传 PMU MSR，会在某些代宿主 CPU 上让早期启动偶发一般保护错误，DragonFlyBSD 受影响最重。只有你确实要在虚拟机里用 perf、pmcstat 或别的性能分析器时才打开。只对有硬件加速的 x86_64 有影响。

--tcg

Force pure software emulation, ignoring KVM, HVF and WHPX. Slow, but it works for any guest when acceleration misbehaves.

$ anyvm --os tribblix --tcg

强制纯软件模拟，忽略 KVM、HVF 和 WHPX。慢，但加速出问题时任何系统都能靠它跑起来。

Running a command

直接跑命令

-- <cmd...>

Everything after -- is executed inside the guest, and AnyVM exits with that command's status. This is the form to use in scripts and CI.

$ anyvm --os freebsd -- uname -a
$ anyvm --os freebsd -- sh -lc "id; uname -a"
$ anyvm --os ubuntu -v "$PWD:/src" -- sh -lc "cd /src && make test"

-- 后面的一切都在客户机里执行，AnyVM 用那条命令的退出码退出。写脚本和 CI 时就该用这种形式。