1.\" Copyright (c) 2002, 2003 Marko Zec <zec@fer.hr> 2.\" Copyright (c) 2009 University of Zagreb 3.\" Copyright (c) 2009 FreeBSD Foundation 4.\" 5.\" All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.\" $FreeBSD$ 29.\" 30.Dd August 25, 2009 31.Dt VIMAGE 8 32.Os 33.Sh NAME 34.Nm vimage 35.Nd manage virtual network stacks 36.Sh SYNOPSIS 37.Nm 38.Op Fl c | m 39.Ar vname 40.Op Ar param=value ... 41.Nm 42.Fl d 43.Ar vname 44.Nm 45.Fl l 46.Op Fl rvj 47.Op Ar vname 48.Nm 49.Fl i 50.Ar vname ifname 51.Op Ar newifname 52.Nm 53.Ar vi_name 54.Op command ... 55.Sh DESCRIPTION 56The 57.Nm 58utility is an alternative user interface for controlling virtual network 59stacks in FreeBSD, aimed primarily at supporting legacy applications 60which are not yet converted to using 61.Xr jail 8 , 62.Xr jexec 8 , 63and 64.Xr jls 8 . 65. 66.Ss Overview 67A virtual image or vimage is a jail with its own independent network 68stack instance. 69Every process, socket and network interface present in the system is always 70attached to one, and only one, virtual network stack instance (vnet). 71During system bootup sequence a default vnet is created to which all the configured 72interfaces and user processes are initially attached. 73Assuming that enough system resources are available, a user with sufficient 74privileges can create and manage a hierarchy of subordinated virtual images. 75The 76.Nm 77command allows for creation, deletion and monitoring of virtual images, 78as well as for execution of arbitrary processes in a targeted virtual image. 79.Ss Invocation 80If invoked with no modifiers, the 81.Nm 82command spawns a new interactive shell in virtual image 83.Ar vname . 84If optional additional arguments following 85.Ar vname 86are provided, the first of those will be executed in place of the 87interactive shell, and the rest of the arguments will be passed as 88arguments to the executed command. 89.Pp 90The following modifiers are available: 91.Bl -tag -width indent 92.It Fl c 93Create a new virtual image named 94.Ar vname . 95Additional arguments, if provided, may be used to specify operating 96parameters different from defaults, in format 97.Ar param=value . 98See 99.Xr jail 8 100for an extensive list of available parameters. 101.It Fl m 102Modify the parameters of a virtual image named 103.Ar vname , 104using the same syntax as with the -c form of the command. 105.It Fl d 106Delete the virtual image 107.Ar vname . 108No processes and/or sockets should exist in the target virtual image 109in order for the delete request to succeed. 110Non-loopback interfaces residing in the target virtual image 111will be reassigned to the virtual image's parent. 112.It Fl l 113List the properties and statistics for virtual images one level below 114the current one in the hierarchy. 115If an optional argument 116.Ar vname 117is provided, only the information regarding the target virtual image 118.Ar vname 119is displayed. 120With the optional 121.Op Ar -r 122switch enabled the list will include all virtual images below the 123current level in the vimage hierarchy. 124Enabling the optional 125.Op Ar -v 126or 127.Op Ar -j 128switches results in a more detailed output. 129.It Fl i 130Move interface 131.Ar ifname 132to the target virtual image 133.Ar vname . 134Interfaces will be automatically renamed to 135.So 136ethXX 137.Sc , 138unless an optional argument specifying the desired interface name 139.Op Ar newifname 140is provided. 141.El 142.Sh EXAMPLES 143Create a new virtual image named 144.So v1 145.Sc , 146which is allowed to create and manage an own subhierarchy of vimages: 147.Pp 148.Dl vimage -c v1 children.max=100 149.Pp 150Execute the 151.So ifconfig 152.Sc command in the virtual image 153.So v1 154.Sc : 155.Pp 156.Dl vimage v1 ifconfig 157.Pp 158Move the interface 159.So vlan0 160.Sc to the virtual image 161.So v1 162.Sc while renaming the interface as 163.So 164ve0 165.Sc : 166.Pp 167.Dl vimage -i v1 vlan0 ve0 168.Pp 169Show the status information for virtual image 170.So v1 171.Sc : 172.Pp 173.Dl vimage -lv v1 174.Sh DIAGNOSTICS 175The 176.Nm 177command exits 0 on success, and >0 if an error occurs. 178.Sh SEE ALSO 179.Xr jail 8 , 180.Xr jexec 8 , 181.Xr jls 8 182.Sh HISTORY 183Network stack virtualization framework first appeared as a patchset 184against the 185.Fx 4.7 186kernel in 2002, and was maintained outside of the main FreeBSD tree. 187As a result of a project sponsored by the FreeBSD Foundation and 188Stiching NLNet, integrated virtualized network stack first appeared in 189.Fx 8.0 . 190.Sh AUTHORS 191.An Marko Zec Aq Mt zec@fer.hr 192.Sh BUGS 193Deletion of vimages / vnets is known to leak kernel memory and fail at 194stopping various timers, hence may lead to system crashes. 195