xref: /freebsd/usr.sbin/bhyveload/bhyveload.8 (revision a5921bc3653e2e286715e6fe8d473ec0d02da38c)
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
35guest 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
49is used to load a
50.Fx
51guest inside a
52.Xr bhyve 4
53virtual machine.
54.Pp
55.Nm
56is based on
57.Xr loader 8
58and will present an interface identical to the
59.Fx
60loader on the user's terminal.
61This behavior can be changed by specifying a different OS loader.
62.Pp
63The virtual machine is identified as
64.Ar vmname
65and will be created if it does not already exist.
66.Sh OPTIONS
67The following options are available:
68.Bl -tag -width indent
69.It Fl c Ar cons-dev
70.Ar cons-dev
71is a
72.Xr tty 4
73device to use for
74.Nm
75terminal I/O.
76.Pp
77The text string "stdio" is also accepted and selects the use of
78unbuffered standard I/O. This is the default value.
79.It Fl d Ar disk-path
80The
81.Ar disk-path
82is the pathname of the guest's boot disk image.
83.It Fl e Ar name=value
84Set the
85.Fx
86loader environment variable
87.Ar name
88to
89.Ar value .
90.Pp
91The option may be used more than once to set more than one environment
92variable.
93.It Fl h Ar host-path
94The
95.Ar host-path
96is the directory at the top of the guest's boot filesystem.
97.It Fl l Ar os-loader
98Specify a different OS loader.
99By default
100.Nm
101will use
102.Pa /boot/userboot.so ,
103which presents a standard
104.Fx
105loader.
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
112is the amount of memory allocated to the guest.
113.Pp
114The
115.Ar mem-size
116argument may be suffixed with one of
117.Cm K ,
118.Cm M ,
119.Cm G
120or
121.Cm T
122(either upper or lower case) to indicate a multiple of
123Kilobytes, Megabytes, Gigabytes or Terabytes
124respectively.
125.Pp
126The default value of
127.Ar mem-size
128is 256M.
129.It Fl C
130Include guest memory in the core file when
131.Nm
132dumps core.
133This is intended for debugging an OS loader as it allows inspection of
134the guest memory.
135.It Fl S
136Wire guest memory.
137.El
138.Sh EXAMPLES
139To create a virtual machine named
140.Ar freebsd-vm
141that boots off the ISO image
142.Pa /freebsd/release.iso
143and has 1GB memory allocated to it:
144.Pp
145.Dl "bhyveload -m 1G -d /freebsd/release.iso freebsd-vm"
146.Pp
147To create a virtual machine named
148.Ar test-vm
149with 256MB of memory allocated, the guest root filesystem under the host
150directory
151.Pa /user/images/test
152and terminal I/O sent to the
153.Xr nmdm 4
154device
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
166first appeared in
167.Fx 10.0 ,
168and was developed at NetApp Inc.
169.Sh AUTHORS
170.Nm
171was developed by
172.An -nosplit
173.An Neel Natu Aq Mt neel@FreeBSD.org
174at NetApp Inc with a lot of help from
175.An Doug Rabson Aq Mt dfr@FreeBSD.org .
176.Sh BUGS
177.Nm
178can only load
179.Fx
180as a guest.
181