Source / qemu-toolkit / qemu-toolkit-configuration.7.html

Full commit
<!DOCTYPE html>
  <meta http-equiv='content-type' value='text/html;charset=utf8'>
  <meta name='generator' value='Ronn/v0.7.3 ('>
  <title>qemu-toolkit-configuration(7) - configuration for qemu-toolkit</title>
  <style type='text/css' media='all'>
  /* style: man */
  body#manpage {margin:0}
  .mp {max-width:100ex;padding:0 9ex 1ex 4ex}
  .mp p,.mp pre,.mp ul,.mp ol,.mp dl {margin:0 0 20px 0}
  .mp h2 {margin:10px 0 0 0}
  .mp > p,.mp > pre,.mp > ul,.mp > ol,.mp > dl {margin-left:8ex}
  .mp h3 {margin:0 0 0 4ex}
  .mp dt {margin:0;clear:left}
  .mp dt.flush {float:left;width:8ex}
  .mp dd {margin:0 0 0 9ex}
  .mp h1,.mp h2,.mp h3,.mp h4 {clear:left}
  .mp pre {margin-bottom:20px}
  .mp pre+h2,.mp pre+h3 {margin-top:22px}
  .mp h2+pre,.mp h3+pre {margin-top:5px}
  .mp img {display:block;margin:auto}
  .mp {display:none}
  .mp,.mp code,.mp pre,.mp tt,.mp kbd,.mp samp,.mp h3,.mp h4 {font-family:monospace;font-size:14px;line-height:1.42857142857143}
  .mp h2 {font-size:16px;line-height:1.25}
  .mp h1 {font-size:20px;line-height:2}
  .mp {text-align:justify;background:#fff}
  .mp,.mp code,.mp pre,.mp pre code,.mp tt,.mp kbd,.mp samp {color:#131211}
  .mp h1,.mp h2,.mp h3,.mp h4 {color:#030201}
  .mp u {text-decoration:underline}
  .mp code,.mp strong,.mp b {font-weight:bold;color:#131211}
  .mp em,.mp var {font-style:italic;color:#232221;text-decoration:none}
  .mp a,.mp a:link,.mp a:hover,.mp a code,.mp a pre,.mp a tt,.mp a kbd,.mp a samp {color:#0000ff}
  .mp {font-weight:normal;color:#434241}
  .mp pre {padding:0 4ex}
  .mp pre code {font-weight:normal;color:#434241}
  .mp h2+pre,h3+pre {padding-left:0}, li {margin:3px 0 10px 0;padding:0;float:left;width:33%;list-style-type:none;text-transform:uppercase;color:#999;letter-spacing:1px} {width:100%} {text-align:left} {text-align:center;letter-spacing:4px} {text-align:right;float:right}
  <style type='text/css' media='all'>
  /* style: toc */
  .man-navigation {display:block !important;position:fixed;top:0;left:113ex;height:100%;width:100%;padding:48px 0 0 0;border-left:1px solid #dbdbdb;background:#eee}
  .man-navigation a,.man-navigation a:hover,.man-navigation a:link,.man-navigation a:visited {display:block;margin:0;padding:5px 2px 5px 30px;color:#999;text-decoration:none}
  .man-navigation a:hover {color:#111;text-decoration:underline}
  The following styles are deprecated and will be removed at some point:
  div#man, div#man, div#man ol.head, div#man

  The .man-page, .man-decor, .man-head, .man-foot, .man-title, and
  .man-navigation should be used instead.
<body id='manpage'>
  <div class='mp' id='man'>

  <div class='man-navigation' style='display:none'>
    <a href="#NAME">NAME</a>
    <a href="#SYNTAX">SYNTAX</a>
    <a href="#SEE-ALSO">SEE ALSO</a>

  <ol class='man-decor man-head man head'>
    <li class='tl'>qemu-toolkit-configuration(7)</li>
    <li class='tc'>qemu-toolkit</li>
    <li class='tr'>qemu-toolkit-configuration(7)</li>

  <h2 id="NAME">NAME</h2>
<p class="man-name">
  <code>qemu-toolkit-configuration</code> - <span class="man-whatis">configuration for qemu-toolkit</span>

<h2 id="SYNTAX">SYNTAX</h2>

<p>The tool <code>vmadm</code> reads all files ending in <code>.rb</code> from <code>/etc/qemu-toolkit</code> on
startup. It expects these Ruby scripts to define virtual machines using the
syntax defined below.</p>

<h3 id="basic-vm-definition">basic vm definition</h3>

<p>A virtual machine definition is written in a Ruby-DSL and looks like this:</p>

<pre><code>virtual_machine "myvm" do
  # Options go here! You'd need at least one disk to start.

<p>Since the definition is Ruby, nothing stops you from doing more complicated
things like connecting to a database or generating definitions using method
calls. Here's an example we've used in the wild:</p>

<pre><code>def lan name, mac
  virtual_machine(name) do
    nic 'eth0', macaddr: mac, via: 'lan0'

# Allows for very short VM definitions:
lan 'vm1', '1:8:20:52:a6:7e'

<h3 id="available-options">available options</h3>

<p>Here's a list of configuration options within the virtual_machine declaration:</p>

<dt>cpus <var>NUMBER</var></dt><dd><p>Configures the number of SMP cpus simulated to the guest system.
You should not configure more SMP cpus than you have physical CPU cores

<pre><code># configures 4 SMP cpus
cpus 4      
<dt>disk <var>DEVICE_PATH</var></dt><dd><p>Add a disk drive to the guest system. <var>DEVICE_PATH</var> should be the
quoted full path to a block device.</p>

<p>This is a macro that will define a <code>virtio</code>-device and automatically number
your drives from 0 to N. If you're looking for more immediate control
over qemu options, use the <code>drive</code>-option.</p>

<pre><code># Use a zvol block device
disk '/dev/zvol/dsk/pool1/myvm/disk1'
<dt>drive <var>OPTIONS</var></dt><dd><p>Directly add a drive directive to qemu options. If you use this, you'll
need to provide all key-value pairs for the directive as a Ruby hash. Note
that if you do not specify 'index', your drive will get the next free disk
index. (as is the case with <code>disk</code>) For the full list of options, please
refer to the <a href="">QEMU documentation</a>.</p>

<pre><code># Manual drive configuration:
drive if: 'floppy', file: 'floppy.dsk'
<dt>net <var>TYPE</var>, <var>OPTIONS</var></dt><dd><p>Manual network configuration. This gives you full access to QEMU options,
with the disadvantage of a slightly more complicated set of options.
Here's what you would need to do to duplicate the convencience macro <code>nic</code>

<pre><code>net :vnic, vlan: 1, name: 'vm1', ifname: 'vm1', 
  macaddr: '1:8:20:52:a6:7e'
net :nic, vlan: 1, name: "vm1", model: "virtio", 
  macaddr: '1:8:20:52:a6:7e'
<dt>nic <var>NAME</var>, <var>OPTIONS</var></dt><dd><p>Add a virtual network card to the guest. Virtual network cards are made
to correspond to vnic links on the host system. These vnic links are
automatically generated for you, all you have to do is to specify a <code>via:</code>
option here.</p>

<p>The <code>via:</code> option takes either physical links or etherstub switches as
You can also specify a VLAN tag, separated by a colon. (ie: e1000g0:4)</p>

<p>nic <code>model:</code> will default to <code>virtio</code>.</p>

<p>NOTE: QEMU/kvm on Illumos will default to providing a single pseudo-nic
that has a DHCP server attached to it by default. If you do not specify
a <code>nic</code>, this is what you'll get.</p>

<pre><code># Create eth0 interface with given mac address via 'igb1'.
nic 'eth0', macaddr: '2:8:20:52:a6:7e', via: 'igb1'
<dt>ram <var>MEGABYTES</var></dt><dd><p>Configures the amount of RAM the guest system sees. Note that the qemu
on Illumos locks memory down for the guest and never swaps it out. This
means that you cannot simulate RAM you don't have available. (free)</p>

<pre><code># One gigabyte of RAM should be enough for everyone. (default)
ram 1024
<dt>vnc <var>PORT</var></dt><dd><p>Enables VNC server on port <var>PORT</var>. Caution: This will listen for
connections from all networks and allow unauthorized access to the guests
console. Don't use this in real world deployments. Instead, use <code>vmadm
console</code> or connect directly to the unix socket using socat.</p>

<pre><code># Make vnc listen on a given port: (5900 + display = tcp/ip port)
vnc_display 0
<dt>extra_arg <var>ARGUMENT</var></dt><dd><p>Extra argument for QEMU, appended to the QEMU command line on launch. If
you'd like to do something that you cannot achieve with the above options,
this is your last resort.</p>

<p>Note that we're interested in extending the DSL for common use cases, so
you might want to mention your extra_arg usage on the mailing list and
get proper treatment from qemu-toolkit.</p>

<pre><code># Arguments that are appended to the qemu launch command line: 
extra_arg '-foo'

<h2 id="SEE-ALSO">SEE ALSO</h2>

<p><a class="man-ref" href="qemu-toolkit-overview.7.html">qemu-toolkit-overview<span class="s">(7)</span></a>, <a class="man-ref" href="qemu-toolkit-install.7.html">qemu-toolkit-install<span class="s">(7)</span></a>,
<a class="man-ref" href="qemu-toolkit-configuration.7.html">qemu-toolkit-configuration<span class="s">(7)</span></a>, <a class="man-ref" href="storadm.1.html">storadm<span class="s">(1)</span></a>, <a class="man-ref" href="vmadm.1.html">vmadm<span class="s">(1)</span></a>, <a class="man-ref" href="README.7.html">README<span class="s">(7)</span></a></p>

  <ol class='man-decor man-foot man foot'>
    <li class='tl'></li>
    <li class='tc'>November 2012</li>
    <li class='tr'>qemu-toolkit-configuration(7)</li>