EMU(7) Standards, Environments, and Macros EMU(7)
emu - zone brand for running a virtual machine instance under the QEMU
hypervisor
An emu branded zone uses the brands(7) framework to provide an
environment for running a virtual machine under the QEMU hypervisor.
NOTE: This brand requires that the `TRIBqemu' package be installed in
the global zone. Some of the less common CPU architectures will
require the `TRIBqemu-extra' package to also be installed.
emu zones are configured mostly via custom attributes in the zone
configuration.
Supported attributes are:
arch architecture
The emulated architecture for the guest; one of:
aarch64
alpha
arm
avr
cris
hppa
i386
loongarch64
m68k
microblaze
microblazeel
mips
mips64
mips64el
mipsel
nios2
or1k
ppc
ppc64
riscv32
riscv64
rx
s390x
sh4
sh4eb
sparc
sparc64
tricore
x86_64
xtensa
xtensaeb
There is no default, this option must be specified.
bootdisk path[,serial=serial]
Specifies a ZFS volume dataset name which will be attached to
the guest as the boot disk. Additional disks can be specified
using the disk attribute, see below.
If the optional serial number is not provided, one will be
automatically generated from the disk index. The ZFS volume
must also be mapped into the zone using a device block as shown
in the example below.
A suitable ZFS volume can be created using the `zfs create -V'
command, for example:
zfs create -V 30G rpool/bootdisk2
cdrom[N] path
Specifies the path to one or more CD/DVD image (.iso) files
that will be inserted into virtual CD/DVD drive(s) in the
guest. To specify multiple image files, create multiple
attributes with different values of N, starting with 0. If
only a single CD image is required, N can be omitted.
Each image file must also be mapped into the zone using an fs
block, as shown in the example below.
cloud-init on|off|filename|URL
When this option is enabled, and set to on or a filename, the
guest will be booted with a small CD image attached that
provides configuration data that cloud-init can use to
automatically configure the guest operating system. When a
file is provided, this is used directly for the provided
user-data. If any network interfaces are configured with an
allowed-address property, then that address will be provided
along with the configuration data. See also the dns-domain,
password, resolvers and sshkey options.
If a URL is provided, then that is passed to the guest system
as the source of the full meta-data.
console options
This parameter configures where the guest's console device is
presented. The default value is zconsole,id=console0 which
means that the guest's console can be accessed via:
zlogin -C <zone>
cpu model
Select the CPU model. The available models depend on the
selected architecture. For further help, run the qemu emulator
for an architecture directly with -cpu help:
% qemu-system-aarch64 -cpu help
Available CPUs:
a64fx
arm1026
arm1136
arm1136-r2
arm1176
...
disk[N] dataset[,serial=serial]
Specifies one or more ZFS volume dataset names which will be
attached to the guest as disks. To attach multiple disks,
create multiple attributes with different values of N. In that
case, the disk will be presented on target N. If only a single
disk is required, N can be omitted. The disks specified via
the disk attribute are in addition to the system boot disk,
which is specified using bootdisk.
If the optional serial number is not provided, one will be
automatically generated from the disk index. Each ZFS volume
must also be mapped into the zone using a device block as shown
in the example below.
diskif type
Specifies the type of interface to which the disks will be
attached. Available options are:
+o virtio (default)
netif type
Specifies the type of network interface that will be used for
the interfaces presented to the guest. Available options are:
+o virtio-net-pci (default)
+o virtio-net-device
+o e1000
password string|hash|filename
When the cloud-init option is enabled, the provided password
will be passed to the guest which can use it to set the
password for the default user. Depending on the guest, this
may be the root user or a distribution-dependant initial user.
The password can be provided as a fixed string, a pre-computed
hash or a path to a file that contains the desired password or
password hash, relative to the global zone root.
ram size[KMGT]
Specify the guest's physical memory size. The size argument
may be suffixed with one of K, M, G or T to indicate a multiple
of kibibytes, mebibytes, gibibytes or tebibytes. If no suffix
is given, the value is assumed to be in mebibytes.
The default value, if this attribute is not specified, is 1G.
dns-domain domainname
The DNS domain name for the guest. Included in the data passed
to the guest when the cloud-init option is enabled.
extra[N]
Any extra options to be passed directly to the emu hypervisor.
To add multiple options, create multiple attributes with
different values of N. If only a single extra option is
required, N can be omitted.
resolvers resolver[,resolver...]
A comma-delimited list of DNS resolver IP addresses. These are
included in the data passed to the guest when the cloud-init
option is enabled.
rng on|off
Set to on to attach a virtio random number generator (RNG) to
the guest (default: off).
sshkey string|filename
When the cloud-init option is enabled, the provided sshkey will
be passed to the guest which can use it to set the authorised
SSH keys for the default user and/or the root user. sshkey can
be provided as a fixed string or a path to a file that contains
the desired public key.
uuid uuid
Specifies the unique identifier for the virtual machine. If
this attribute is not set, a random UUID will be generated when
the zone is first installed.
vcpus number
Specify the number of guest virtual CPUs. The default value is
1.
vga off|on
Select whether the guest is booted with or without a display
device. Setting this attribute to off results in a "headless"
guest.
vnc on|off|options
This parameter controls whether a virtual framebuffer is
attached to the guest and made available via VNC. Available
options are:
on An alias for unix:/tmp/vm.vnc which creates the VNC
socket within /tmp inside the zone.
off Disable the framebuffer. This is the same as omitting
the vnc attribute.
unix:path
Sets up a VNC server on a UNIX socket at the specified
path. Note that this path is relative to the zone
root.
Example 1: An example emu zone is shown below:
create -t emu
set zonepath=/zones/emu
add net
set allowed-address=10.0.0.112/24
set physical=vm0
end
add device
set match=/dev/zvol/rdsk/rpool/emu
end
add attr
set name=arch
set type=string
set value=aarch64
end
add attr
set name=cpu
set type=string
set value=cortex-a53
end
add attr
set name=ram
set type=string
set value=2G
end
add attr
set name=vcpus
set type=string
set value=8
end
add attr
set name=bootdisk
set type=string
set value=rpool/emu0
end
add fs
set dir=/rpool/iso/debian-9.4.0-arm64-netinst.iso
set special=/rpool/iso/debian-9.4.0-arm64-netinst.iso
set type=lofs
add options ro
add options nodevices
end
add attr
set name=cdrom
set type=string
set value=/rpool/iso/debian-9.4.0-arm64-netinst.iso
end
Example 2: A similar configuration, this time using the zap(1) create-
zone subcommand.
zap create-zone -z emu1 -x 10.0.0.112 -t emu -V 8G -c 8 -M aarch64:cortex-a53 -I /rpool/iso/debian-9.4.0-arm64-netinst.iso
mdb(1), proc(1), zap(1), brands(7), privileges(7),
resource_controls(7), zones(7), zfs(8), zoneadm(8), zonecfg(8)
Tribblix February 8, 2026 Tribblix
NAME
emu - zone brand for running a virtual machine instance under the QEMU
hypervisor
DESCRIPTION
An emu branded zone uses the brands(7) framework to provide an
environment for running a virtual machine under the QEMU hypervisor.
NOTE: This brand requires that the `TRIBqemu' package be installed in
the global zone. Some of the less common CPU architectures will
require the `TRIBqemu-extra' package to also be installed.
CONFIGURATION
emu zones are configured mostly via custom attributes in the zone
configuration.
Supported attributes are:
arch architecture
The emulated architecture for the guest; one of:
aarch64
alpha
arm
avr
cris
hppa
i386
loongarch64
m68k
microblaze
microblazeel
mips
mips64
mips64el
mipsel
nios2
or1k
ppc
ppc64
riscv32
riscv64
rx
s390x
sh4
sh4eb
sparc
sparc64
tricore
x86_64
xtensa
xtensaeb
There is no default, this option must be specified.
bootdisk path[,serial=serial]
Specifies a ZFS volume dataset name which will be attached to
the guest as the boot disk. Additional disks can be specified
using the disk attribute, see below.
If the optional serial number is not provided, one will be
automatically generated from the disk index. The ZFS volume
must also be mapped into the zone using a device block as shown
in the example below.
A suitable ZFS volume can be created using the `zfs create -V'
command, for example:
zfs create -V 30G rpool/bootdisk2
cdrom[N] path
Specifies the path to one or more CD/DVD image (.iso) files
that will be inserted into virtual CD/DVD drive(s) in the
guest. To specify multiple image files, create multiple
attributes with different values of N, starting with 0. If
only a single CD image is required, N can be omitted.
Each image file must also be mapped into the zone using an fs
block, as shown in the example below.
cloud-init on|off|filename|URL
When this option is enabled, and set to on or a filename, the
guest will be booted with a small CD image attached that
provides configuration data that cloud-init can use to
automatically configure the guest operating system. When a
file is provided, this is used directly for the provided
user-data. If any network interfaces are configured with an
allowed-address property, then that address will be provided
along with the configuration data. See also the dns-domain,
password, resolvers and sshkey options.
If a URL is provided, then that is passed to the guest system
as the source of the full meta-data.
console options
This parameter configures where the guest's console device is
presented. The default value is zconsole,id=console0 which
means that the guest's console can be accessed via:
zlogin -C <zone>
cpu model
Select the CPU model. The available models depend on the
selected architecture. For further help, run the qemu emulator
for an architecture directly with -cpu help:
% qemu-system-aarch64 -cpu help
Available CPUs:
a64fx
arm1026
arm1136
arm1136-r2
arm1176
...
disk[N] dataset[,serial=serial]
Specifies one or more ZFS volume dataset names which will be
attached to the guest as disks. To attach multiple disks,
create multiple attributes with different values of N. In that
case, the disk will be presented on target N. If only a single
disk is required, N can be omitted. The disks specified via
the disk attribute are in addition to the system boot disk,
which is specified using bootdisk.
If the optional serial number is not provided, one will be
automatically generated from the disk index. Each ZFS volume
must also be mapped into the zone using a device block as shown
in the example below.
diskif type
Specifies the type of interface to which the disks will be
attached. Available options are:
+o virtio (default)
netif type
Specifies the type of network interface that will be used for
the interfaces presented to the guest. Available options are:
+o virtio-net-pci (default)
+o virtio-net-device
+o e1000
password string|hash|filename
When the cloud-init option is enabled, the provided password
will be passed to the guest which can use it to set the
password for the default user. Depending on the guest, this
may be the root user or a distribution-dependant initial user.
The password can be provided as a fixed string, a pre-computed
hash or a path to a file that contains the desired password or
password hash, relative to the global zone root.
ram size[KMGT]
Specify the guest's physical memory size. The size argument
may be suffixed with one of K, M, G or T to indicate a multiple
of kibibytes, mebibytes, gibibytes or tebibytes. If no suffix
is given, the value is assumed to be in mebibytes.
The default value, if this attribute is not specified, is 1G.
dns-domain domainname
The DNS domain name for the guest. Included in the data passed
to the guest when the cloud-init option is enabled.
extra[N]
Any extra options to be passed directly to the emu hypervisor.
To add multiple options, create multiple attributes with
different values of N. If only a single extra option is
required, N can be omitted.
resolvers resolver[,resolver...]
A comma-delimited list of DNS resolver IP addresses. These are
included in the data passed to the guest when the cloud-init
option is enabled.
rng on|off
Set to on to attach a virtio random number generator (RNG) to
the guest (default: off).
sshkey string|filename
When the cloud-init option is enabled, the provided sshkey will
be passed to the guest which can use it to set the authorised
SSH keys for the default user and/or the root user. sshkey can
be provided as a fixed string or a path to a file that contains
the desired public key.
uuid uuid
Specifies the unique identifier for the virtual machine. If
this attribute is not set, a random UUID will be generated when
the zone is first installed.
vcpus number
Specify the number of guest virtual CPUs. The default value is
1.
vga off|on
Select whether the guest is booted with or without a display
device. Setting this attribute to off results in a "headless"
guest.
vnc on|off|options
This parameter controls whether a virtual framebuffer is
attached to the guest and made available via VNC. Available
options are:
on An alias for unix:/tmp/vm.vnc which creates the VNC
socket within /tmp inside the zone.
off Disable the framebuffer. This is the same as omitting
the vnc attribute.
unix:path
Sets up a VNC server on a UNIX socket at the specified
path. Note that this path is relative to the zone
root.
EXAMPLES
Example 1: An example emu zone is shown below:
create -t emu
set zonepath=/zones/emu
add net
set allowed-address=10.0.0.112/24
set physical=vm0
end
add device
set match=/dev/zvol/rdsk/rpool/emu
end
add attr
set name=arch
set type=string
set value=aarch64
end
add attr
set name=cpu
set type=string
set value=cortex-a53
end
add attr
set name=ram
set type=string
set value=2G
end
add attr
set name=vcpus
set type=string
set value=8
end
add attr
set name=bootdisk
set type=string
set value=rpool/emu0
end
add fs
set dir=/rpool/iso/debian-9.4.0-arm64-netinst.iso
set special=/rpool/iso/debian-9.4.0-arm64-netinst.iso
set type=lofs
add options ro
add options nodevices
end
add attr
set name=cdrom
set type=string
set value=/rpool/iso/debian-9.4.0-arm64-netinst.iso
end
Example 2: A similar configuration, this time using the zap(1) create-
zone subcommand.
zap create-zone -z emu1 -x 10.0.0.112 -t emu -V 8G -c 8 -M aarch64:cortex-a53 -I /rpool/iso/debian-9.4.0-arm64-netinst.iso
SEE ALSO
mdb(1), proc(1), zap(1), brands(7), privileges(7),
resource_controls(7), zones(7), zfs(8), zoneadm(8), zonecfg(8)
Tribblix February 8, 2026 Tribblix