Ready to take your JavaScript development to the next level? Meet npm Enterprise - the ultimate in enterprise JavaScript. Learn more »


1.4.2 • Public • Published


Zcage is a zone manager for illumos inspired by FreeBSD's iocage and SmartOS's vmadm. It's intended to be easy to use with a simple command line syntax. To use zcage you need an user account with Primary administrator role and install nodejs

Zcage only has been tested in OmniOSce.

Installing using npm

Currently there is a bug in npm 5.X so npm 4.X must be used to install

  • npm install npm@4 -g

  • npm install zcage -g

Installing from source

# git clone 
# cd zcage &&  pfexec npm install -g  

Options when creating a zone

ram (brand: ALL , not required, defaults to 1GB)

  • Assigns maximum amount of memory allowed for the container to use.

net (brand: ALL , required)

  • Configures network for zone format is vnic|ip/mask|gateway

alias (brand: ALL, not required, defaults to UUID v4)

  • Sets the zone name for later reference instead of UUID v4.

quota (brand: ALL, not required)

  • Sets disk quota for zone.

limitpriv (brand: ALL, not required)

  • Adds privileges to a zone, priveleges must be comman separated values.

fs-allowed (brand: ALL, not required)

  • Allows file system mounts other than the default

with-image (brand: LX, required)

  • Uses the image specified when creating a zone.

disk (brand: BHYVE, required)

  • Sets the disk that bhyve will use to start the vm.

autoboot (brand: ALL, not required, defaults to false)

  • Sets if a zone should be started at boot.

brand (brand: ALL, not required, defaults to sparse)

  • Sets the zone brand for zone creation.

cdrom (brand: BHYVE, not required)

  • Specifies iso to use when booting a bhyve vm)

hostbridge (brand: BHYVE, not required, defaults to intel)

  • Specifies which hostbridge should bhyve present to the guest.

cpu (brand: BHYVE, not required, defaults to 1)

  • Specified the number of cpus the vm will use.


  • zcage needs to be activated before any zone could be created, it will create all the needed datasets for zone management.
# zcage activate 


First we need to setup a virtual nic for zones using dladm. Currently each container need to have a different vnic otherwise it won't start.

# dladm create-vnic -l igb0 omni0 
  • Create a container using virtual network interface vnic0 using ip: mask and as gateway and memory capped to use 2GB of RAM.
# zcage create --alias=test07 --net "vnic0||" --ram 2gb 
  • Update the capped memory of the previously defined zone and also set/update a disk quota
# zcage update -z test07 --ram 4gb --quota 16G
  • List remotely available linux images from Joyent
# zcage images --list  avail 
UID                                            NAME                            VERSION         OS                      PUBLISHED
f7c19252-c998-11e4-be95-3315493f3741             lx-centos-6                     20150313        linux           2015-03-13T15:52:35Z
818cc79e-ceb3-11e4-99ee-7bc8c674e754             lx-ubuntu-14.04                 20150320        linux           2015-03-20T03:45:09Z
116deb8c-cf03-11e4-9b2d-7b1066800a6a             lx-debian-7                     20150320        linux           2015-03-20T13:14:41Z
eb4128ec-cf12-11e4-960d-8780cec6463f             lx-centos-6                     20150320        linux           2015-03-20T15:08:0
  • List locally available linux images to create lx branded zones.
# zcage images --list local 
UUID                                            NAME                            VERSION         OS                      PUBLISHED
96bb1fac-c87d-11e5-b5bf-ff4703459205             alpine-3                        20160201        linux           2016-02-01T00:49:02Z

LX branded zones

  • First you need install the lx brand package in OmniOSce:
# pkg install pkg:/system/zones/brand/lx 
  • Pull a linux image to create a lx branded zone
# zcage pull --image  96bb1fac-c87d-11e5-b5bf-ff4703459205 
  • To create a lx branded zone, you need to specify the image to use and brand as lx
# zcage create --net "vnic0||" --ram 2gb  --with-image 96bb1fac-c87d-11e5-b5bf-ff4703459205 --alias lxvm --brand lx 

Now you can reference the container by it's alias test07. If you don't provide an alias a UUID will be generated.

  • Update the zone to allow it to use more ram if needed and restrict maximum lwps to 3000
# zcage update -z test07 --ram 6gb --max-lwps 3000 
  • Destroy the container (cannot be undone)
# zcage destroy -z test07 
  • List zones
# zcage list 
UUID                                     TYPE           STATE            ALIAS
2ff83af6-01a3-622a-e831-f65966465624     OS             stopped          nodejs
ecc9627e-6515-cd96-9fd0-b06973e4423f     OS             stopped          test07
2585e1a7-ef50-eb1d-e85b-cbf5631ced5e     OS             stopped          test08
c53b4cb4-f970-6d07-e64b-916c7fa23fc6     OS             stopped          test09
  • General information about zone
# zcage info -z test07 

Bhyve branded zones

First you need install bhyve and bhyve brand packages in OmniOSce:

# pfexec pkg install system/bhyve 

And also the bhyve brand

# pfexec pkg install system/zones/brand/bhyve   

To create a bhyve branded zone, first we need to create a disk for it to use:

# zfs create -V 30G rpool/vm0 

Then create the zone using the newly created disk.

# zcage create --brand bhyve --net "net6||" --ram 2gb  --alias bhyve0  --disk=rpool/vm0 

You could specify the iso which to use at boot using the --with-iso option

# zcage start -z bhyve0 --with-iso /home/neirac/isos/FreeBSD-11.2-RELEASE-amd64-bootonly.iso 

Then you could connect to the newly created bhyve vm using vnc, to obtain the port just use the info command.

#zcage info -z bhyve0 



Bhyve Demo



  • Resource control
  • Simple to use
  • Exclusive IP networking by default
  • Supports for brands sparse, ipkg, lipkg, bhyve and lx.


  • Improve info command to obtain more information from zones.
  • Check if a vnc port is already used by a bhyve branded zone.
  • Add boot order flag for bhyve zones.
  • Import docker images for lx zones.
  • Check if ip is already in use by a zone.
  • Add tests
  • Clean up json in info command
  • Improve documentation


npm i zcage

Downloadsweekly downloads









last publish


  • avatar
Report a vulnerability