VIMAGE(8)

NAME
vimage - manage virtual network stacks

SYNOPSIS
vimage [-c | -m] vname [param=value ...]
vimage -d vname
vimage -l [-rvj] [vname]
vimage -i vname ifname [newifname]
vimage vi_name [command ...]

DESCRIPTION
The vimage utility is an alternative user interface for controlling virtual network stacks in FreeBSD, aimed primarily at supporting legacy applications which are not yet converted to using jail(8), jexec(8), and jls(8).

  Overview
A virtual image or vimage is a jail with its own independent network stack instance. Every process, socket and network interface present in the system is always attached to one, and only one, virtual network stack instance (vnet). During system bootup sequence a default vnet is created to which all the configured interfaces and user processes are initially attached. Assuming that enough system resources are are available, a user with sufficient privileges can create and manage a hierarchy of subordinated virtual images. The vimage command allows for creation, deletion and monitoring of virtual images, as well as for execution of arbitrary processes in a targeted virtual image.

  Invocation
If invoked with no modifiers, the vimage command spawns a new interactive shell in virtual image vname. If optional additional arguments following vname are provided, the first of those will be executed in place of the interactive shell, and the rest of the arguments will be passed as arguments to the executed command.

The following modifiers are available:

-c  Create a new virtual image named vname. Additional arguments, if provided, may be used to specify operating parameters different from defaults, in format param=value. See jail(8) for an extensive list of available parameters.

-m  Modify the parameters of a virtual image named vname, using the same syntax as with the -c form of the command.

-d  Delete the virtual image vname. No processes and/or sockets should exist in the target virtual image in order for the delete request to succeed. Non-loopback interfaces residing in the target virtual image will be reassigned to the virtual image's parent.

-l  List the properties and statistics for virtual images one level below the current one in the hierarchy. If an optional argument vname is provided, only the information regarding the target virtual image vname is displayed. With the optional [-r] switch enabled the list will include all virtual images below the current level in the vimage hierarchy. Enabling the optional [-v] or [-j] switches results in a more detailed output.

-i  Move interface ifname to the target virtual image vname. Interfaces will be automatically renamed to ‘ ethXX ’, unless an optional argument specifying the desired interface name [newifname] is provided.

EXAMPLES
Create a new virtual image named ‘v1 ’, which is allowed to create and manage an own subhierarchy of vimages:

    vimage -c v1 children.max=100

Execute the ‘ifconfig ’ command in the virtual image ‘v1 ’:

    vimage v1 ifconfig

Move the interface ‘vlan0 ’ to the virtual image ‘v1 ’ while renaming the interface as ‘ ve0 ’:

    vimage -i v1 vlan0 ve0

Show the status information for virtual image ‘v1 ’:

    vimage -lv v1

DIAGNOSTICS
The vimage command exits 0 on success, and >0 if an error occurs.

SEE ALSO
jail(8) jexec(8) jls(8)

HISTORY
Network stack virtualization framework first appeared as a patchset against the FreeBSD 4.7 kernel in 2002, and was maintained outside of the main FreeBSD tree. As a result of a project sponsored by the FreeBSD Foundation and Stiching NLNet, integrated virtualized network stack first appeared in FreeBSD 8.0.

BUGS
Deletion of vimages / vnets is known to leak kernel memory and fail at stopping various timers, hence may lead to system crashes.

AUTHOR
Marko Zec <zec@fer.hr>