Running Motor OS
A build produces disk images and a set of scripts in
vm_images/release/ (from src/build-motor-os.sh or
make BUILD=release) or vm_images/debug/ (from make).
This page describes what is in the images and how to start and reach a VM.
The images
| Image | Format | Contents |
|---|---|---|
motor-os-base.img | raw, 64 MB | The minimal bootable system: sys-init, sys-tty, strobe, russhd; the rush shell, sysbox and its command scripts; the red editor and rmux. No DNS resolver. |
motor-os.qcow2 | qcow2, 256 MB | The standard image: everything in base plus the DNS resolver, httpd and httpd-axum, kibim, ripgrep, and the C library configuration. |
motor-os-dev.qcow2 | qcow2, 4 GB | The developer image: the standard image plus the native LLVM and rustc toolchains,
Lorry, Gears, curl, Lua, mdbg, the test suites, source snapshots, and this website
under /devtools/www. See Developer image. |
motor-os-system-tty.img | raw, 64 MB | A test-only variant of the base image whose serial console runs with the System role.
Built by make system-tty.img, not by the build script, and used by
src/tests/test-system-tty.sh. |
Every image is built by the imager from a YAML description in src/imager/
and a declarative permission policy; see Filesystem for the
layout and permissions, and Building Motor OS for how the images
are produced. QEMU and Cloud Hypervisor accept both formats; Firecracker supports only the
raw images.
Hypervisors and scripts
Motor OS boots via MBR under QEMU and via PVH under Cloud Hypervisor and Firecracker.
For the latter two, the image directory also holds kloader and
initrd, the kernel loader and initial RAM disk the hypervisor loads directly.
QEMU is installed by the build; Cloud Hypervisor and Firecracker are not, and the scripts
expect cloud-hypervisor-static and firecracker on
PATH. The scripts are:
| Script | What it does |
|---|---|
create-tap.sh | Creates the moto-tap interface the VMs use
(host side 192.168.4.1/24 and 2001:db8::1/64), enables IPv4 forwarding,
and adds an nftables masquerade rule so VMs can reach the Internet. The build script performs
the same steps, so after a build the interface exists; run this after a host reboot, because
the settings do not survive one. Needs sudo. |
run-qemu.sh | Runs the image named by MOTO_IMAGE (default
motor-os.qcow2) under QEMU with -nographic, so the serial console is
your terminal. MOTO_SMP (default 4) and MOTO_MEMORY_MIB (default 1024)
set the VM size. MOTO_QEMU_USER_NET=1 uses QEMU's user-mode networking instead of
the tap, which needs no sudo; the VM's SSH port is then localhost:10023. Extra
arguments are passed to QEMU. A lock file prevents two VMs from sharing the tap. |
run-qemu-echr.sh | The same, with QEMU's escape character moved off Ctrl+A (to Ctrl+T) so that rmux can use it as its prefix. |
run-chv.sh | Runs the image under Cloud Hypervisor, with the same
variables and defaults. The API socket and the log go under /tmp
(MOTO_CHV_RUNTIME_DIR). |
run-fc.sh | Runs a raw image under Firecracker: by default
motor-os-base.img with 2 vCPUs and 64 MiB. The generated configuration, the
socket, and the log go under /tmp (MOTO_FC_RUNTIME_DIR). |
run-dev.sh | Runs the developer image with 8 vCPUs and 8 GiB of
RAM; --vmm qemu|chv selects the hypervisor, and arguments after
-- are passed to it. |
ssh-into-motor-os-vm.sh | Opens an SSH session to the running VM using the
bundled test.key; any arguments are passed to ssh, so
./ssh-into-motor-os-vm.sh ls /user/bin runs a command. |
The VM's address is 192.168.4.2. Serial console output, including the
kernel log and the logs of headless services, appears in the terminal that started the
VM; keep it, because it is the only diagnostic channel when networking or sys-io itself
has failed. When deploying to a cloud, enable the provider's serial console capture before
first boot.
The console
The VM boots to a rush prompt on the serial console. The console
is a plain byte stream driven by sys-tty: there is no terminal emulator in the
guest, so the terminal you started the VM from does the emulation. Full-screen programs
such as red and rmux ask that terminal for its size; see
Terminals.
Connecting over SSH
russhd, the SSH server, is started by sys-init on every image and
listens on port 2222 in the shipped configuration (/system/cfg/sshd.toml).
It supports password and public-key authentication, interactive shells with a pty,
command execution without one (ssh host command), and the SFTP subsystem, so
scp and sftp work for copying files in and out.
ssh -p 2222 -o IdentitiesOnly=yes -i test.key [email protected]
scp -P 2222 -o IdentitiesOnly=yes -i test.key ./hello [email protected]:/user/bin/The shipped sshd.toml contains a test host key, a test user, and a test
password; regenerate all of them before any deployment that is reachable from a network
you do not control.
Networking from the VM
Every image configures its network from /system/cfg/sys-net.toml;
the shipped file gives the VM the static addresses 192.168.4.2/24 and
2001:db8::2/64, default routes through the host side of
moto-tap, and 8.8.8.8 as the DNS server. With the masquerade
rule that the build, or create-tap.sh, installs on the host,
ping google.com and curl (on the developer image) reach the
Internet. See Networking for the configuration format and
for DHCP.
Stopping the VM
Exiting the serial console exits the VM (type exit in the terminal).
You can also press the hypervisor's escape sequence (Ctrl+A, X under QEMU) or kill the hypervisor process. Motor FS is journaled and is designed to survive a power-off.