1 .\" Copyright (c) 2002, 2003 Marko Zec <zec@fer.hr>
2 .\" Copyright (c) 2009 University of Zagreb
3 .\" Copyright (c) 2009 FreeBSD Foundation
5 .\" All rights reserved.
7 .\" Redistribution and use in source and binary forms, with or without
8 .\" modification, are permitted provided that the following conditions
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.
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
35 .Nd manage virtual network stacks
40 .Op Ar param=value ...
58 utility is an alternative user interface for controlling virtual network
59 stacks in FreeBSD, aimed primarily at supporting legacy applications
60 which are not yet converted to using
67 A virtual image or vimage is a jail with its own independent network
68 stack instance. Every process, socket and network interface present
69 in the system is always attached to one, and only one, virtual network
70 stack instance (vnet).
71 During system bootup sequence a default vnet
72 is created to which all the configured interfaces and user processes
73 are initially attached.
74 Assuming that enough system resources are
75 are available, a user with sufficient privileges can create and manage
76 a hierarchy of subordinated virtual images.
79 command allows for creation, deletion and monitoring of virtual images,
80 as well as for execution of arbitrary processes in a targeted virtual
83 If invoked with no modifiers, the
85 command spawns a new interactive shell in virtual image
87 If optional additional arguments following
89 are provided, the first of those will be executed in place of the
90 interactive shell, and the rest of the arguments will be passed as
91 arguments to the executed command.
93 The following modifiers are available:
94 .Bl -tag -width indent
96 Create a new virtual image named
98 Additional arguments, if provided, may be used to specify operating
99 parameters different from defaults, in format
103 for an extensive list of available parameters.
105 Modify the parameters of a virtual image named
107 using the same syntax as with the -c form of the command.
109 Delete the virtual image
111 No processes and/or sockets should exist in the target virtual image
112 in order for the delete request to succeed. Non-loopback interfaces
113 residing in the target virtual image will be reassigned to the virtual
116 List the properties and statistics for virtual images one level
117 below the current one in the hierarchy. If an optional argument
119 is provided, only the information regarding the target virtual image
124 switch enabled the list will include all virtual images below the
125 current level in the vimage hierarchy.
126 Enabling the optional
130 switches results in a more detailed output.
134 to the target virtual image
136 Interfaces will be automatically renamed to
140 unless an optional argument specifying the desired interface name
145 Create a new virtual image named
148 which is allowed to create and manage an own subhierarchy of vimages:
150 .Dl vimage -c v1 children.max=100
154 .Sc command in the virtual image
158 .Dl vimage v1 ifconfig
162 .Sc to the virtual image
164 .Sc while renaming the interface as
169 .Dl vimage -i v1 vlan0 ve0
171 Show the status information for virtual image
179 command exits 0 on success, and >0 if an error occurs.
185 Network stack virtualization framework first appeared as a patchset
186 against the FreeBSD 4.7 kernel in 2002, and was maintained outside
187 of the main FreeBSD tree.
188 As a result of a project sponsored by the FreeBSD Foundation and
189 Stiching NLNet, integrated virtualized network stack first appeared
192 .An Marko Zec Aq Mt zec@fer.hr
194 Deletion of vimages / vnets is known to leak kernel memory and fail at
195 stopping various timers, hence may lead to system crashes.