Hi, Here's an intial stab at a FAQ entry for vmm.
It covers two common setups: * a vmm guest with network access via the host's wired network * a vmm guest with network access via the host's wireless network Please critique. Once we have the details right, I can run it past tj. Some other thoughts that arose as a result of writing this: * Unless I am wrong there is no way to start a single VM which is defined in vm.conf. Up until now I have been doing `vmctl reload`, which is not quite the same. (there is an XXX in the diff about this). * Should `vmctl status` list all the VMs defined in vm.conf (and any manually started VMs), indicating whether they are powered up or down? * rebooting a guest does not work. * attaching to a console by name would be nice touch. Thanks Index: faq/faq10.html =================================================================== RCS file: /home/edd/cvsync/www/faq/faq10.html,v retrieving revision 1.253 diff -u -p -r1.253 faq10.html --- faq/faq10.html 2 Oct 2016 21:19:04 -0000 1.253 +++ faq/faq10.html 15 Oct 2016 16:08:48 -0000 @@ -43,6 +43,11 @@ <li><a href="#YP_client" >Setting up a YP client</a> </ul> <li><a href="#Patches" >Keeping OpenBSD up to date</a> +<li><a href="#VMM" >Virtual machines with vmm(4)</a> +<ul> + <li><a href="#VMM_simple" >Ths simplest vmm(4) setup</a> + <li><a href="#VMM_wireless" >Using vmm(4) when the host uses wireless networking</h3> +</ul> </ul> <hr> @@ -895,5 +900,280 @@ At other times, will require recompiling patched library. <p> + +<h2 id="VMM">Virtual machines with vmm(4)</a></h2> + +<p> +OpenBSD ships with a virtual machine monitor, +<a href="http://man.openbsd.org/vmm";>vmm(4)</a>, which is capable of hosting +OpenBSD guests. +This section shows how to set up the common use-cases. + +<h3 id="VMM_simple">The simplest vmm(4) setup</h3> + +<p> +Suppose that we have a machine connected to the internet via a wired +<tt>re0</tt> network interface, and that we wish to install an OpenBSD guest VM +with internet access. +Suppose that <tt>re0</tt> gets its network address via DHCP, and that we want +the guest machine to use that same DHCP server. + +<p> +First we make a directory to hold the disk image and kernel: + +<pre><blockquote> +# mkdir -p /vms/my_vm +# cd /vms/my_vm +</pre></blockquote> + +<p> +Next we make a disk image: + +<pre><blockquote> +vmctl create disk.img -s 4.5G +</pre></blockquote> + +The <tt>-s</tt> argument specifies the size of the disk image. +Note that the image is lazily allocated. + +<p> +Next we need an OpenBSD kernel to boot. +We are going to run the OpenBSD installer, so we need a <tt>bsd.rd</tt> (at +least initially). +For the sake of example, let's use the <tt>bsd.rd</tt> from the host: + +<pre><blockquote> +# cp /bsd.rd . +</pre></blockquote> + +<p> +Now we have to tell the host machine about the configuration of the VM. +In this FAQ we will do this using a +<a href="http://man.openbsd.org/vm.conf";<tt>vm.conf(5)</tt></a>, so as to bring +the VM up at boot time (but note that the VM configuration could be specified +when starting a VM manually with +<a href="http://man.openbsd.org/vmctl";><tt>vmctl(8)</tt></a>). + +<p> +In <tt>/etc/vm.conf</tt>, put the following: + +<pre><blockquote> +switch "my_switch" { + interface bridge0 + add re0 +} + +vm "my_vm" { + memory 512M + disk "/vms/my_vm/disk.img" + kernel "/vms/my_vm/bsd.rd" + interface tap { switch "my_switch" } +} +</pre></blockquote> + +<p> +This should be mostly self explanatory, but the switch configuration perhaps +requires some more discussion. +When the VM starts, a +<a href="http://man.openbsd.org/tap";><tt>tap(4)</tt></a> network interface will +be created. +This interface corresponds to the +<a href="http://man.openbsd.org/vio";><tt>vio(4)</tt></a> network interface +inside the guest. +By defining a "switch", and assigning it to our VM, +<a href="http://man.openbsd.org/vmd";><tt>vmd(8)</tt></a> will later add the +host-side <a href="http://man.openbsd.org/tap";><tt>tap(4)</tt></a> interface to +an (automatically created) +<a href="http://man.openbsd.org/bridge";><tt>bridge(4)</tt></a> interface. +By specifying <tt>add re0</tt> in the switch definition, we also add the host's +wired interface into the bridge, thus granting internet access to the guest. + +<p> +Now let's bring the guest up: + +<pre><blockquote> +# rcctl enable vmd # start VMs at boot +# rcctl start vmd +</pre></blockquote> + +<p> +If all went to plan, +<a href="http://man.openbsd.org/rcctl";><tt>rcctl(8)</tt></a> should tell us the +VM is up: + +<pre><blockquote> + ID PID VCPUS MAXMEM CURMEM TTY NAME + 1 73539 1 512MB 91MB /dev/ttyp7 my_vm +</pre></blockquote> + +<p> +If the guest is not listed, look in <tt>/var/log/daemon</tt> for clues as to +what went wrong. + +<p> +Assuming all is well, we can now connect to the guest's console using the VM's +ID: + +<pre><blockquote> +# vmctl console 1 +Connected to /dev/ttyp7 (speed 9600) +</pre></blockquote> + +<p> +Hit enter to see the next line of console output: + +<pre><blockquote> +(i)nstall, (u)pgrade, (a)utoinstall or (s)hell? +</pre></blockquote> + +<p> +It's the installer! +We can now install the guest (the installation procedure is detailed in the +<a href="faq4.html">installation guide</a>). +When asked for network settings, we can specify to use DHCP, and the +host-network's DHCP server will answer. + +<p> +Once installation is complete, we can halt the guest, and swap the ramdisk +kernel for a normal kernel: + +<pre><blockquote> +# halt -p +syncing disks... done +</pre></blockquote> + +<p> +When the guest is down, hit enter and you are back at the host's shell: + +<pre><blockquote> +[EOT] +# cp /bsd . +# vi /etc/vm.conf # update kernel setting to: kernel "/vms/my_vm/bsd" +</pre></blockquote> + +<p> +Finally, we can restart the VM and it should boot multi-user. +Note that the guest's ID will have changed. + +<pre><blockquote> +# vmctl reload # XXX better way? How to start a single VM defined in vm.conf? +# vmctl status + ID PID VCPUS MAXMEM CURMEM TTY NAME + 2 73539 1 512MB 91MB /dev/ttyp7 my_vm +# vmctl console 2 +</pre></blockquote> + +Hit enter: + +<pre><blockquote> +OpenBSD/amd64 (foo.bar) (tty00) + +login: +</pre></blockquote> + +<h3 id="VMM_wireless">Using vmm(4) when the host uses wireless networking</h3> + +<p> +Unfortunately, the setup described in the previous section would not have +worked if the host's wired <tt>re0</tt> interface had been a wireless interface. +Due to a limitation of the ieee802.11 standard, wireless interfaces can not +participate in network bridges. +To work around this, we can give the guest VM its own network and use network +address translation (NAT) to the host's network, but the upshot is we can no +longer use the host network's DHCP server. +We would need to either use static addresses, or our own DHCP server. +Here we demonstrate the latter option. + +<p> +Suppose that we have a host machine with internet access via a wireless +<tt>iwn0</tt> interface on the <tt>192.168.1.0/24</tt> network, and that we +want to install an OpenBSD guest which will get an IP address via our own DHCP +server on the <tt>192.168.10.0/24</tt> network. +The guest will access the internet via a NAT between the two networks and +let's assume we are using the same kernel and disk image paths as before. + +<p> +Although we could run the DHCP server directly on the VM's +<a href="http://man.openbsd.org/tap";><tt>tap(4)</tt></a> +interface, this is awkward, as the interface will come and go as the guest VM +comes up and down. +Instead, we can use an always-existing +<a href="http://man.openbsd.org/vether";<tt>vether(4)</tt></a> interface and +serve up DHCP there, later ensuring that this interface gets bridged to the +VM's <a href="http://man.openbsd.org/tap";</a><tt>tap(4)</tt></a> interface. + +<p> +Let's make a <tt>vether0</tt> interface: + +<pre><blockquote> +# echo "inet 192.168.10.1 255.255.255.0" > /etc/hostname.vether0 +# sh /etc/netstart vether0 +</pre></blockquote> + +<p> +Next, put the following in <tt>/etc/dhcpd.conf</tt>: + +<pre><blockquote> +subnet 192.168.10.0 netmask 255.255.255.0 { + option routers 192.168.10.1; + option domain-name-servers 192.168.1.1; + option domain-name "home"; + range 192.168.10.2 192.168.10.10; +} +</pre></blockquote> + +<p> +And start the DHCP server, being careful to serve up DHCP on only +<tt>vether0</tt>: + +<pre><blockquote> +# echo "dhcpd_flags=vether0" >> /etc/rc.conf.local +# rcctl enable dhcpd +# rcctl start dhcpd +</pre></blockquote> + +<p> +We need to add a <a href="http://man.openbsd.org/pf";<tt>pf(4)</tt></a> rule to +do the NATting. +Put in the correct place in <tt>/etc/pf.conf</tt>: + +<pre><blockquote> +match out on iwn0 inet from vether0:network to any nat-to (iwn0) +</pre></blockquote> + +<p> +And to finish off the NAT configuration: + +<pre><blockquote> +# pfctl -f /etc/pf.conf +# echo "net.inet.ip.forwarding=1" >> /etc/sysctl.conf +# sysctl net.inet.ip.forwarding=1 +net.inet.ip.forwarding: 0 -> 1 +</pre></blockquote> + +<p> +Now the following +<a href="http://man.openbsd.org/vm.conf";</a><tt>vm.conf(5)</tt></a> +should work: + +<pre><blockquote> +switch "my_switch" { + add vether0 + interface bridge0 +} + +vm "my_vm" { + memory 512M + disk "/vms/my_vm/disk.img" + kernel "/vms/my_vm/bsd.rd" + interface tap { switch "my_switch" } +} +</pre></blockquote> + +<p> +Be aware that if you move the host machine between networks, (e.g. you take +your laptop from your home to your work) you will have to update the DHCP +server configuration to offer up the correct DNS server and router addresses. + </body> </html> Index: faq/index.html =================================================================== RCS file: /home/edd/cvsync/www/faq/index.html,v retrieving revision 1.495 diff -u -p -r1.495 index.html --- faq/index.html 2 Oct 2016 21:16:26 -0000 1.495 +++ faq/index.html 15 Oct 2016 16:08:48 -0000 @@ -151,6 +151,7 @@ that are not covered in the FAQ. <li><a href="faq10.html#SKey" >Using S/Key</a> <li><a href="faq10.html#Dir" >Directory services</a> <li><a href="faq10.html#Patches" >Keeping OpenBSD up to date</a> +<li><a href="faq10.html#VMM" >Virtual machines with vmm(4)</a> </ul> <h3><a href="faq11.html">The X Window System</a></h3> -- Best Regards Edd Barrett http://www.theunixzoo.co.uk
