docs/drvbhyve.html

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml">
   4 <!--
   5         This file is autogenerated from drvbhyve.html.in
   6         Do not edit this file. Changes will be lost.
   7       -->
   8   <head>
   9     <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
  10     <link rel="stylesheet" type="text/css" href="main.css" />
  11     <link rel="SHORTCUT ICON" href="32favicon.png" />
  12     <title>libvirt: Bhyve driver</title>
  13     <meta name="description" content="libvirt, virtualization, virtualization API" />
  14   </head>
  15   <body>
  16     <div id="header">
  17       <div id="headerLogo"></div>
  18       <div id="headerSearch">
  19         <form action="search.php" enctype="application/x-www-form-urlencoded" method="get"><div>
  20             <input id="query" name="query" type="text" size="12" value="" />
  21             <input id="submit" name="submit" type="submit" value="Search" />
  22           </div></form>
  23       </div>
  24     </div>
  25     <div id="body">
  26       <div id="menu">
  27         <ul class="l0"><li>
  28             <div>
  29               <a title="Front page of the libvirt website" class="inactive" href="index.html">Home</a>
  30             </div>
  31           </li><li>
  32             <div>
  33               <a title="Details of new features and bugs fixed in each release" class="inactive" href="news.html">News</a>
  34             </div>
  35           </li><li>
  36             <div>
  37               <a title="Applications known to use libvirt" class="inactive" href="apps.html">Applications</a>
  38             </div>
  39           </li><li>
  40             <div>
  41               <a title="Get the latest source releases, binary builds and get access to the source repository" class="inactive" href="downloads.html">Downloads</a>
  42             </div>
  43           </li><li>
  44             <div>
  45               <a title="Information for users, administrators and developers" class="active" href="docs.html">Documentation</a>
  46               <ul class="l1"><li>
  47                   <div>
  48                     <a title="How to compile libvirt" class="inactive" href="compiling.html">Compiling</a>
  49                   </div>
  50                 </li><li>
  51                   <div>
  52                     <a title="Information about deploying and using libvirt" class="inactive" href="deployment.html">Deployment</a>
  53                   </div>
  54                 </li><li>
  55                   <div>
  56                     <a title="Overview of the logical subsystems in the libvirt API" class="inactive" href="intro.html">Architecture</a>
  57                   </div>
  58                 </li><li>
  59                   <div>
  60                     <a title="Description of the XML formats used in libvirt" class="inactive" href="format.html">XML format</a>
  61                   </div>
  62                 </li><li>
  63                   <div>
  64                     <a title="Hypervisor specific driver information" class="active" href="drivers.html">Drivers</a>
  65                     <ul class="l2"><li>
  66                         <div>
  67                           <a title="Driver the Xen hypervisor" class="inactive" href="drvxen.html">Xen</a>
  68                         </div>
  69                       </li><li>
  70                         <div>
  71                           <a title="Driver for QEMU, KQEMU, KVM and Xenner" class="inactive" href="drvqemu.html">QEMU / KVM</a>
  72                         </div>
  73                       </li><li>
  74                         <div>
  75                           <a title="Driver for the Linux native container API" class="inactive" href="drvlxc.html">Linux Container</a>
  76                         </div>
  77                       </li><li>
  78                         <div>
  79                           <a title="Pseudo-driver simulating APIs in memory for test suites" class="inactive" href="drvtest.html">Test</a>
  80                         </div>
  81                       </li><li>
  82                         <div>
  83                           <a title="Driver providing secure remote to the libvirt APIs" class="inactive" href="drvremote.html">Remote</a>
  84                         </div>
  85                       </li><li>
  86                         <div>
  87                           <a title="Driver for the OpenVZ container technology" class="inactive" href="drvopenvz.html">OpenVZ</a>
  88                         </div>
  89                       </li><li>
  90                         <div>
  91                           <a title="Driver for the User Mode Linux technology" class="inactive" href="drvuml.html">UML</a>
  92                         </div>
  93                       </li><li>
  94                         <div>
  95                           <a title="Driver for the storage management APIs" class="inactive" href="storage.html">Storage</a>
  96                         </div>
  97                       </li><li>
  98                         <div>
  99                           <a title="Driver for VirtualBox" class="inactive" href="drvvbox.html">VirtualBox</a>
 100                         </div>
 101                       </li><li>
 102                         <div>
 103                           <a title="Driver for VMware ESX" class="inactive" href="drvesx.html">VMware ESX</a>
 104                         </div>
 105                       </li><li>
 106                         <div>
 107                           <a title="Driver for VMware Workstation / Player" class="inactive" href="drvvmware.html">VMware Workstation / Player</a>
 108                         </div>
 109                       </li><li>
 110                         <div>
 111                           <a title="Driver for Microsoft Hyper-V" class="inactive" href="drvhyperv.html">Microsoft Hyper-V</a>
 112                         </div>
 113                       </li><li>
 114                         <div>
 115                           <a title="Driver for IBM PowerVM" class="inactive" href="drvphyp.html">IBM PowerVM</a>
 116                         </div>
 117                       </li><li>
 118                         <div>
 119                           <a title="Driver for Parallels Cloud Server" class="inactive" href="drvparallels.html">Parallels</a>
 120                         </div>
 121                       </li><li>
 122                         <div>
 123                           <span class="active">Bhyve</span>
 124                         </div>
 125                       </li></ul>
 126                   </div>
 127                 </li><li>
 128                   <div>
 129                     <a title="Reference manual for the C public API" class="inactive" href="html/index.html">API reference</a>
 130                   </div>
 131                 </li><li>
 132                   <div>
 133                     <a title="Bindings of the libvirt API for other languages" class="inactive" href="bindings.html">Language bindings</a>
 134                   </div>
 135                 </li><li>
 136                   <div>
 137                     <a title="Working on the internals of libvirt API, driver and daemon code" class="inactive" href="internals.html">Internals</a>
 138                   </div>
 139                 </li><li>
 140                   <div>
 141                     <a title="A guide and reference for developing with libvirt" class="inactive" href="devguide.html">Development Guide</a>
 142                   </div>
 143                 </li><li>
 144                   <div>
 145                     <a title="Command reference for virsh" class="inactive" href="virshcmdref.html">Virsh Commands</a>
 146                   </div>
 147                 </li><li>
 148                   <div>
 149                     <a title="Project governance and code of conduct" class="inactive" href="governance.html">Governance</a>
 150                   </div>
 151                 </li></ul>
 152             </div>
 153           </li><li>
 154             <div>
 155               <a title="User contributed content" class="inactive" href="http://wiki.libvirt.org">Wiki</a>
 156             </div>
 157           </li><li>
 158             <div>
 159               <a title="Frequently asked questions" class="inactive" href="http://wiki.libvirt.org/page/FAQ">FAQ</a>
 160             </div>
 161           </li><li>
 162             <div>
 163               <a title="How and where to report bugs and request features" class="inactive" href="bugs.html">Bug reports</a>
 164             </div>
 165           </li><li>
 166             <div>
 167               <a title="How to contact the developers via email and IRC" class="inactive" href="contact.html">Contact</a>
 168             </div>
 169           </li><li>
 170             <div>
 171               <a title="Available test suites for libvirt" class="inactive" href="testsuites.html">Test suites</a>
 172             </div>
 173           </li><li>
 174             <div>
 175               <a title="Miscellaneous links of interest related to libvirt" class="inactive" href="relatedlinks.html">Related Links</a>
 176             </div>
 177           </li><li>
 178             <div>
 179               <a title="Overview of all content on the website" class="inactive" href="sitemap.html">Sitemap</a>
 180             </div>
 181           </li></ul>
 182       </div>
 183       <div id="content">
 184         <h1>Bhyve driver</h1>
 185         <ul><li>
 186             <a href="#uri">Connections to the Bhyve driver</a>
 187           </li><li>
 188             <a href="#exconfig">Example guest domain XML configurations</a>
 189           </li><li>
 190             <a href="#usage">Guest usage / management</a>
 191             <ul><li>
 192                 <a href="#console">Connecting to a guest console</a>
 193               </li><li>
 194                 <a href="#xmltonative">Converting from domain XML to Bhyve args</a>
 195               </li></ul>
 196           </li></ul>
 197         <p>
 198 Bhyve is a FreeBSD hypervisor. It first appeared in FreeBSD 10.0. However, it's
 199 recommended to keep tracking FreeBSD 10-STABLE to make sure all new features
 200 of bhyve are supported.
 201
 202 In order to enable bhyve on your FreeBSD host, you'll need to load the <code>vmm</code>
 203 kernel module. Additionally, <code>if_tap</code> and <code>if_bridge</code> modules
 204 should be loaded for networking support.
 205 </p>
 206         <p>
 207 Additional information on bhyve could be obtained on <a href="http://bhyve.org/" shape="rect">bhyve.org</a>.
 208 </p>
 209         <h2>
 210           <a name="uri" shape="rect" id="uri">Connections to the Bhyve driver</a>
 211           <a class="headerlink" href="#uri" title="Permalink to this headline">¶</a>
 212         </h2>
 213         <p>
 214 The libvirt bhyve driver is a single-instance privileged driver. Some sample
 215 connection URIs are:
 216 </p>
 217         <pre xml:space="preserve">
 218 bhyve:///system                     (local access)
 219 bhyve+unix:///system                (local access)
 220 bhyve+ssh://root@example.com/system (remote access, SSH tunnelled)
 221 </pre>
 222         <h2>
 223           <a name="exconfig" shape="rect" id="exconfig">Example guest domain XML configurations</a>
 224           <a class="headerlink" href="#exconfig" title="Permalink to this headline">¶</a>
 225         </h2>
 226         <h3>Example config</h3>
 227         <p>
 228 The bhyve driver in libvirt is in its early stage and under active development. So it supports
 229 only limited number of features bhyve provides. All the supported features could be found
 230 in this sample domain XML.
 231 </p>
 232         <p>
 233 A limitation that is not obvious from this sample domain XML is that currently only a
 234 single network and a single disk device are supported for each domain (as PCI slot allocation code
 235 in libvirt bhyve driver is yet to be implemented).
 236 </p>
 237         <pre xml:space="preserve">
 238 &lt;domain type='bhyve'&gt;
 239   &lt;name&gt;bhyve&lt;/name&gt;
 240   &lt;uuid&gt;df3be7e7-a104-11e3-aeb0-50e5492bd3dc&lt;/uuid&gt;
 241     &lt;memory&gt;219136&lt;/memory&gt;
 242     &lt;currentMemory&gt;219136&lt;/currentMemory&gt;
 243     &lt;vcpu&gt;1&lt;/vcpu&gt;
 244     &lt;os&gt;
 245        &lt;type&gt;hvm&lt;/type&gt;
 246     &lt;/os&gt;
 247     &lt;features&gt;
 248       &lt;apic/&gt;
 249       &lt;acpi/&gt;
 250     &lt;/features&gt;
 251     &lt;clock offset='utc'/&gt;
 252     &lt;on_poweroff&gt;destroy&lt;/on_poweroff&gt;
 253     &lt;on_reboot&gt;restart&lt;/on_reboot&gt;
 254     &lt;on_crash&gt;destroy&lt;/on_crash&gt;
 255     &lt;devices&gt;
 256       &lt;disk type='file'&gt;
 257         &lt;driver name='file' type='raw'/&gt;
 258         &lt;source file='/path/to/bhyve_freebsd.img'/&gt;
 259         &lt;target dev='hda' bus='sata'/&gt;
 260       &lt;/disk&gt;
 261       &lt;interface type='bridge'&gt;
 262         &lt;model type='virtio'/&gt;
 263         &lt;source bridge="virbr0"/&gt;
 264       &lt;/interface&gt;
 265     &lt;/devices&gt;
 266 &lt;/domain&gt;
 267 </pre>
 268         <h2>
 269           <a name="usage" shape="rect" id="usage">Guest usage / management</a>
 270           <a class="headerlink" href="#usage" title="Permalink to this headline">¶</a>
 271         </h2>
 272         <h3>
 273           <a name="console" shape="rect" id="console">Connecting to a guest console</a>
 274           <a class="headerlink" href="#console" title="Permalink to this headline">¶</a>
 275         </h3>
 276         <p>
 277 Guest console connection is supported through the <code>nmdm</code> device. It could be enabled by adding
 278 the following to the domain XML (<span class="since">Since 1.2.4</span>):
 279 </p>
 280         <pre xml:space="preserve">
 281   ...
 282   &lt;devices&gt;
 283     &lt;serial type="nmdm"&gt;
 284       &lt;source master="/dev/nmdm0A" slave="/dev/nmdm0B"/&gt;
 285     &lt;/serial&gt;
 286   &lt;/devices&gt;
 287   ...</pre>
 288         <p>Make sure to load the <code>nmdm</code> kernel module if you plan to use that.</p>
 289         <p>
 290 Then <code>virsh console</code> command can be used to connect to the text console
 291 of a guest.</p>
 292         <p><b>NB:</b> Some versions of bhyve have a bug that prevents guests from booting
 293 until the console is opened by a client. This bug was fixed in FreeBSD
 294 <a href="http://svnweb.freebsd.org/changeset/base/262884" shape="rect">r262884</a>. If
 295 an older version is used, one either has to open a console manually with <code>virsh console</code>
 296 to let a guest boot or start a guest using:</p>
 297         <pre xml:space="preserve">start --console domname</pre>
 298         <h3>
 299           <a name="xmltonative" shape="rect" id="xmltonative">Converting from domain XML to Bhyve args</a>
 300           <a class="headerlink" href="#xmltonative" title="Permalink to this headline">¶</a>
 301         </h3>
 302         <p>
 303 The <code>virsh domxml-to-native</code> command can preview the actual
 304 <code>bhyve</code> commands that will be executed for a given domain.
 305 It outputs two lines, the first line is a <code>bhyveload</code> command and
 306 the second is a <code>bhyve</code> command.
 307 </p>
 308         <p>Please note that the <code>virsh domxml-to-native</code> doesn't do any
 309 real actions other than printing the command, for example, it doesn't try to
 310 find a proper TAP interface and create it, like what is done when starting
 311 a domain; and always returns <code>tap0</code> for the network interface. So
 312 if you're going to run these commands manually, most likely you might want to
 313 tweak them.</p>
 314         <pre xml:space="preserve">
 315 # virsh -c "bhyve:///system"  domxml-to-native --format bhyve-argv --xml /path/to/bhyve.xml
 316 /usr/sbin/bhyveload -m 214 -d /home/user/vm1.img vm1
 317 /usr/sbin/bhyve -c 2 -m 214 -A -I -H -P -s 0:0,hostbridge -s 3:0,virtio-net,tap0,mac=52:54:00:5d:74:e3 -s 2:0,virtio-blk,/home/user/vm1.img -s 1,lpc -l com1,/dev/nmdm0A vm1
 318 </pre>
 319       </div>
 320     </div>
 321     <div id="footer">
 322       <p id="sponsor">
 323             Sponsored by:<br /><a href="http://et.redhat.com/"><img src="et.png" alt="Project sponsored by Red Hat Emerging Technology" /></a></p>
 324     </div>
 325   </body>
 326 </html>