tools/tools/vimage/vimage.8

   1 .\" Copyright (c) 2002, 2003 Marko Zec <zec@tel.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 June 6, 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 .Ar vi_name
  39 .Op command
  40 .Nm
  41 .Fl c
  42 .Ar vi_name
  43 .Nm
  44 .Fl d
  45 .Ar vi_name
  46 .Nm
  47 .Fl l
  48 .Op Ar vi_name
  49 .Nm
  50 .Fl i
  51 .Ar vi_name interface
  52 .Sh DESCRIPTION
  53 .Nm
  54 command is an interm user interface for controlling the virtual network
  55 stacks in FreeBSD.
  56 .Ss Overview
  57 A virtual image reprepresents an isolated operating environment with its
  58 own independent network stack instance.  Every process, socket and network
  59 interface present in the system is always attached to one, and only one,
  60 virtual image i.e. virtual network stack instance.
  61 During the system bootup sequence default virtual image is created to
  62 which all the configured interfaces and user processes are initially
  63 assigned.
  64 Assuming that enough system resources and per virtual image privileges
  65 are provided, the super-user can create and manage a hierarchy of
  66 subordinated virtual images. The
  67 .Nm
  68 command allows for creation, deletion and monitoring of virtual images,
  69 as well as for execution of arbitrary processes in a targeted virtual
  70 image.
  71 .Ss Invocation
  72 If invoked with no modifiers, the
  73 .Nm
  74 command spawns a new shell process in virtual image
  75 .Ar vi_name .
  76 If provided, the optional arguments following the virtual image name
  77 .Ar vi_name
  78 are interpreted as a standard command line issued at a shell,
  79 otherwise an interactive shell is started in the target virtual image.
  80 .Pp
  81 The following parameters are available:
  82 .Bl -tag -width indent
  83 .It Fl c
  84 Create a new virtual image named
  85 .So
  86 .Ar vi_name
  87 .Sc .
  88 .It Fl d
  89 Delete the virtual image
  90 .Ar vi_name .
  91 No processes and/or sockets should exist in the target virtual image
  92 in order for the delete request to succeed. Non-loopback interfaces
  93 residing in the target virtual image will be reassigned to the virtual
  94 image's parent.
  95 .It Fl l
  96 List the properties and statistics for virtual images one level
  97 below the current one in the hierarchy. If an optional argument
  98 .Ar vi_name
  99 is provided, only the information regarding the target virtual image
 100 .Ar vi_name
 101 is displayed.
 102 .It Fl lr
 103 List the properties and statistics for all virtual images in
 104 the hierarchy of subordinated vimages. If an optional argument
 105 .Ar vi_name
 106 is provided, the hierarchy will be traversed at and below the
 107 .Ar vi_name
 108 level.
 109 .It Fl i
 110 Move the interface
 111 .Ar interface
 112 to the target virtual image
 113 .Ar vi_name .
 114 If the value of
 115 .Ar vi_name
 116 argument is
 117 .So ..
 118 .Sc ,
 119 the interface is returned to the parent of the current virtual image.
 120 .El
 121 .Sh EXAMPLES
 122 Create a new virtual image named
 123 .So v1
 124 .Sc :
 125 .Pp
 126 .Dl vimage -c v1
 127 .Pp
 128 Execute the
 129 .So ifconfig
 130 .Sc command in the virtual image
 131 .So v1
 132 .Sc :
 133 .Pp
 134 .Dl vimage v1 ifconfig
 135 .Pp
 136 Move the interface
 137 .So vlan0
 138 .Sc to the virtual image
 139 .So v1
 140 .Sc :
 141 .Pp
 142 .Dl vimage -i v1 vlan0
 143 .Pp
 144 Show the status information for virtual image
 145 .So v1
 146 .Sc :
 147 .Pp
 148 .Dl vimage -l v1
 149 .Sh DIAGNOSTICS
 150 The
 151 .Nm
 152 command exits 0 on success, and >0 if an error occurs.
 153 .Sh SEE ALSO
 154 .Xr jail 8
 155 .Sh BUGS
 156 If memory allocation failure occurs during the vimage creation, it will remain
 157 undetected/ignored in the current implementation, thus latently scheduling
 158 an almost imminent system crash in the future.
 159 .Sh AUTHOR
 160 .An "Marko Zec" Aq zec@fer.hr
 161 .Sh HISTORY
 162 The
 163 .Nm
 164 facility first appeared as a patch against FreeBSD 4.7-RELEASE in 2002.