usr.sbin/bhyveload/bhyveload.8

   1 .\"
   2 .\" Copyright (c) 2012 NetApp Inc
   3 .\" All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\"
  14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  15 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  16 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  17 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  18 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  19 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  20 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  21 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  22 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  23 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  24 .\" SUCH DAMAGE.
  25 .\"
  26 .\" $FreeBSD$
  27 .\"
  28 .Dd February 26, 2016
  29 .Dt BHYVELOAD 8
  30 .Os
  31 .Sh NAME
  32 .Nm bhyveload
  33 .Nd load a
  34 .Fx
  35 guest inside a bhyve virtual machine
  36 .Sh SYNOPSIS
  37 .Nm
  38 .Op Fl C
  39 .Op Fl S
  40 .Op Fl c Ar cons-dev
  41 .Op Fl d Ar disk-path
  42 .Op Fl e Ar name=value
  43 .Op Fl h Ar host-path
  44 .Op Fl l Ar os-loader
  45 .Op Fl m Ar mem-size
  46 .Ar vmname
  47 .Sh DESCRIPTION
  48 .Nm
  49 is used to load a
  50 .Fx
  51 guest inside a
  52 .Xr bhyve 4
  53 virtual machine.
  54 .Pp
  55 .Nm
  56 is based on
  57 .Xr loader 8
  58 and will present an interface identical to the
  59 .Fx
  60 loader on the user's terminal.
  61 This behavior can be changed by specifying a different OS loader.
  62 .Pp
  63 The virtual machine is identified as
  64 .Ar vmname
  65 and will be created if it does not already exist.
  66 .Sh OPTIONS
  67 The following options are available:
  68 .Bl -tag -width indent
  69 .It Fl c Ar cons-dev
  70 .Ar cons-dev
  71 is a
  72 .Xr tty 4
  73 device to use for
  74 .Nm
  75 terminal I/O.
  76 .Pp
  77 The text string "stdio" is also accepted and selects the use of
  78 unbuffered standard I/O. This is the default value.
  79 .It Fl d Ar disk-path
  80 The
  81 .Ar disk-path
  82 is the pathname of the guest's boot disk image.
  83 .It Fl e Ar name=value
  84 Set the
  85 .Fx
  86 loader environment variable
  87 .Ar name
  88 to
  89 .Ar value .
  90 .Pp
  91 The option may be used more than once to set more than one environment
  92 variable.
  93 .It Fl h Ar host-path
  94 The
  95 .Ar host-path
  96 is the directory at the top of the guest's boot filesystem.
  97 .It Fl l Ar os-loader
  98 Specify a different OS loader.
  99 By default
 100 .Nm
 101 will use
 102 .Pa /boot/userboot.so ,
 103 which presents a standard
 104 .Fx
 105 loader.
 106 .It Fl m Ar mem-size Xo
 107 .Sm off
 108 .Op Cm K | k | M | m | G | g | T | t
 109 .Xc
 110 .Sm on
 111 .Ar mem-size
 112 is the amount of memory allocated to the guest.
 113 .Pp
 114 The
 115 .Ar mem-size
 116 argument may be suffixed with one of
 117 .Cm K ,
 118 .Cm M ,
 119 .Cm G
 120 or
 121 .Cm T
 122 (either upper or lower case) to indicate a multiple of
 123 Kilobytes, Megabytes, Gigabytes or Terabytes
 124 respectively.
 125 .Pp
 126 The default value of
 127 .Ar mem-size
 128 is 256M.
 129 .It Fl C
 130 Include guest memory in the core file when
 131 .Nm
 132 dumps core.
 133 This is intended for debugging an OS loader as it allows inspection of
 134 the guest memory.
 135 .It Fl S
 136 Wire guest memory.
 137 .El
 138 .Sh EXAMPLES
 139 To create a virtual machine named
 140 .Ar freebsd-vm
 141 that boots off the ISO image
 142 .Pa /freebsd/release.iso
 143 and has 1GB memory allocated to it:
 144 .Pp
 145 .Dl "bhyveload -m 1G -d /freebsd/release.iso freebsd-vm"
 146 .Pp
 147 To create a virtual machine named
 148 .Ar test-vm
 149 with 256MB of memory allocated, the guest root filesystem under the host
 150 directory
 151 .Pa /user/images/test
 152 and terminal I/O sent to the
 153 .Xr nmdm 4
 154 device
 155 .Pa /dev/nmdm1B
 156 .Pp
 157 .Dl "bhyveload -m 256MB -h /usr/images/test -c /dev/nmdm1B test-vm"
 158 .Sh SEE ALSO
 159 .Xr bhyve 4 ,
 160 .Xr nmdm 4 ,
 161 .Xr vmm 4 ,
 162 .Xr bhyve 8 ,
 163 .Xr loader 8
 164 .Sh HISTORY
 165 .Nm
 166 first appeared in
 167 .Fx 10.0 ,
 168 and was developed at NetApp Inc.
 169 .Sh AUTHORS
 170 .Nm
 171 was developed by
 172 .An -nosplit
 173 .An Neel Natu Aq Mt neel@FreeBSD.org
 174 at NetApp Inc with a lot of help from
 175 .An Doug Rabson Aq Mt dfr@FreeBSD.org .
 176 .Sh BUGS
 177 .Nm
 178 can only load
 179 .Fx
 180 as a guest.