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.Dd August 25, 2009 29.Dt VIMAGE 8 30.Os 31.Sh NAME 32.Nm vimage 33.Nd manage virtual network stacks 34.Sh SYNOPSIS 35.Nm 36.Op Fl c | m 37.Ar vname 38.Op Ar param=value ... 39.Nm 40.Fl d 41.Ar vname 42.Nm 43.Fl l 44.Op Fl rvj 45.Op Ar vname 46.Nm 47.Fl i 48.Ar vname ifname 49.Op Ar newifname 50.Nm 51.Ar vi_name 52.Op command ... 53.Sh DESCRIPTION 54The 55.Nm 56utility is an alternative user interface for controlling virtual network 57stacks in FreeBSD, aimed primarily at supporting legacy applications 58which are not yet converted to using 59.Xr jail 8 , 60.Xr jexec 8 , 61and 62.Xr jls 8 . 63. 64.Ss Overview 65A virtual image or vimage is a jail with its own independent network 66stack instance. 67Every process, socket and network interface present in the system is always 68attached to one, and only one, virtual network stack instance (vnet). 69During system bootup sequence a default vnet is created to which all the configured 70interfaces and user processes are initially attached. 71Assuming that enough system resources are available, a user with sufficient 72privileges can create and manage a hierarchy of subordinated virtual images. 73The 74.Nm 75command allows for creation, deletion and monitoring of virtual images, 76as well as for execution of arbitrary processes in a targeted virtual image. 77.Ss Invocation 78If invoked with no modifiers, the 79.Nm 80command spawns a new interactive shell in virtual image 81.Ar vname . 82If optional additional arguments following 83.Ar vname 84are provided, the first of those will be executed in place of the 85interactive shell, and the rest of the arguments will be passed as 86arguments to the executed command. 87.Pp 88The following modifiers are available: 89.Bl -tag -width indent 90.It Fl c 91Create a new virtual image named 92.Ar vname . 93Additional arguments, if provided, may be used to specify operating 94parameters different from defaults, in format 95.Ar param=value . 96See 97.Xr jail 8 98for an extensive list of available parameters. 99.It Fl m 100Modify the parameters of a virtual image named 101.Ar vname , 102using the same syntax as with the -c form of the command. 103.It Fl d 104Delete the virtual image 105.Ar vname . 106No processes and/or sockets should exist in the target virtual image 107in order for the delete request to succeed. 108Non-loopback interfaces residing in the target virtual image 109will be reassigned to the virtual image's parent. 110.It Fl l 111List the properties and statistics for virtual images one level below 112the current one in the hierarchy. 113If an optional argument 114.Ar vname 115is provided, only the information regarding the target virtual image 116.Ar vname 117is displayed. 118With the optional 119.Op Ar -r 120switch enabled the list will include all virtual images below the 121current level in the vimage hierarchy. 122Enabling the optional 123.Op Ar -v 124or 125.Op Ar -j 126switches results in a more detailed output. 127.It Fl i 128Move interface 129.Ar ifname 130to the target virtual image 131.Ar vname . 132Interfaces will be automatically renamed to 133.So 134ethXX 135.Sc , 136unless an optional argument specifying the desired interface name 137.Op Ar newifname 138is provided. 139.El 140.Sh EXAMPLES 141Create a new virtual image named 142.So v1 143.Sc , 144which is allowed to create and manage an own subhierarchy of vimages: 145.Pp 146.Dl vimage -c v1 children.max=100 147.Pp 148Execute the 149.So ifconfig 150.Sc command in the virtual image 151.So v1 152.Sc : 153.Pp 154.Dl vimage v1 ifconfig 155.Pp 156Move the interface 157.So vlan0 158.Sc to the virtual image 159.So v1 160.Sc while renaming the interface as 161.So 162ve0 163.Sc : 164.Pp 165.Dl vimage -i v1 vlan0 ve0 166.Pp 167Show the status information for virtual image 168.So v1 169.Sc : 170.Pp 171.Dl vimage -lv v1 172.Sh DIAGNOSTICS 173The 174.Nm 175command exits 0 on success, and >0 if an error occurs. 176.Sh SEE ALSO 177.Xr jail 8 , 178.Xr jexec 8 , 179.Xr jls 8 180.Sh HISTORY 181Network stack virtualization framework first appeared as a patchset 182against the 183.Fx 4.7 184kernel in 2002, and was maintained outside of the main FreeBSD tree. 185As a result of a project sponsored by the FreeBSD Foundation and 186Stiching NLNet, integrated virtualized network stack first appeared in 187.Fx 8.0 . 188.Sh AUTHORS 189.An Marko Zec Aq Mt zec@fer.hr 190.Sh BUGS 191Deletion of vimages / vnets is known to leak kernel memory and fail at 192stopping various timers, hence may lead to system crashes. 193