| QRUN(1) | OpenBSD Reference Manual | QRUN(1) |
| qrun | -i path [-v] [-b interface] [-C path] [-c path] [-M mode] [-m memsize] [-n string] [-o bridge | console | netcfg] [-p path] [-s size] [-u user] [qemu-options] |
By default, user mode network emulation will be used, so no further options are required for quick start usage. See the EXAMPLES section below for other simple usages.
The options -b, -n, -o, and -u require qrun to be executed as root, since they utilize privileged operations.
The options are as follows:
- -b interface
-
Specifies the bridge(4) interface to bridge to a guest network interface. If used multiple times, a new guest network interface will be created for each instance, bridged to the network interfaces in the order specified.
- -C path
-
Specifies the CD-ROM image or device from which to read blocks of data when presenting the guest OS with a simulated atapiscsi(4) CD-ROM device.
- -c path
-
Identical to the -C option, but additionally boots the guest OS from the simulated CD-ROM device.
- -i path
-
Specifies the file or device from which to read blocks of data when presenting the guest OS with a simulated wd(4) device.
- -M mode
-
Changes the machine presented to the guest OS. By default, an i386 machine is presented. The only other valid mode is amd64.
- -m memsize
-
Alters the memory presented to the guest OS. By default, memsize is 128m.
- -n string
-
A string passed to ifconfig(8) to configure the tun(4) device. This is for routing qemu(1) sessions natively and/or NAT-ing them via pf(4). Like the -b option, multiple -n options may be specified, each one coinciding with an interface presented to the guest OS, in the order specified. The -n and -b options may be both used if desired.
- -o bridge=interface,model=nicmodel,macaddr=52:54:01:00:XX:XX
- -o netcfg=string,model=nicmodel,macaddr=52:54:01:00:XX:XX
- -o console=com0,monitor=stdio,serial=unix,vnc=[::]:3
- -o controllertype=<ctype>
-
Provides a more advanced usage of the -b and -n options as well as enabling a serial console to be presented at a terminal prompt. <ctype> can be one of
- ahci
- isa-ide
- lsi53c895a
- virtio-blk-pci
- usb-storage
-
If combined with the -p option and an /etc/boot.conf file containing “set tty com0”, a system may be booted to a serial console in a terminal without requiring graphics. This can be especially useful for running inside tmux(1).
The interface option to bridge may be a physical interface, such as em0, or a special notation:
group:string
This special notation permits multiple qrun instances to be bridged together, by adding the string to the interface group of the bridge(4) instead of bridging to a physical interface. This mainly for the qnet(1) script, but advanced users may choose to use it themselves. The string is limited by interface group limitations and therefore may not end in a number.
- -p path
-
Specifies the tftpboot dir from which to pxeboot(8) the guest OS. The guest virtual machines BIOS will TFTP the file “pxeboot” from the path specified and start executing it as a real system would.
- -s size
-
Specifies the size of the disk image to create, if qrun is auto-creating the disk image.
- -u user
-
Runs qemu(1) as user user. This is recommended if one of the options requiring root privileges is used, as the environment will be set up then the fdpass program will drop privileges to the user specified and qemu will not be running as root.
- -v
- Provides verbose information while setting up bridge(4) and tun(4) interfaces as well as showing the qemu(1) command line used when starting qemu.
The most basic simple usage would be to install a guest OS with user mode networking:
$ qrun -i test.hd -c cd47.iso
After the installation, one would issue “quit” at the “(qemu)” prompt and then start qemu(1) subsequently via:
$ qrun -i test.hd
Another common way to use qrun would be to bridge the native Ethernet to a qemu(1) guest's network interface:
$ sudo qrun -u $USER -i test.hd -b em0
This sets up a bridge(4) interface to connect the em(4) interface of the native system and the tun(4) interface of the qemu(1) guest OS.
The third common way to use qrun would be to route the qemu(1) guest's network interface:
$ sudo qrun -u $USER -i test.hd -n 10.0.1.1/24
This would set up a tun(4) interface with “10.0.1.1 netmask 255.255.255.0” and it would be up to the user to run dhcpd(8) on the tun(4) interface connected to the qemu(1) guest OS.
One final advanced example that most people will not want to bother with but can show the power of qrun:
$ sudo qrun -u $USER -i `pwd`/test.hd \ -o bridge=em0,model=rtl8139,macaddr=52:54:01:00:XX:XX \ -o console=com0 \ -- \ -serial telnet:127.0.0.1:30000,server,nowait \ -monitor telnet:127.0.0.1:40000,server,nowait \ -daemonize
| April 24, 2014 | OpenBSD 5.5 |