qemu-toolkit 0.2.18 → 0.3.0

data/README.md

@@ -0,0 +1,47 @@
+# qemu-toolkit(7) -- A toolkit for running qemu on Illumos / OmniOS
+
+## SYNOPSIS
+
+qemu-toolkit is a small set of scripts to control QEMU kvm virtualised
+machines on a set of illumos hosts. Have a look at 'storadm' and 
+'vmadm' - inline help will show you the possibilities.
+
+## INSTALLATION
+
+qemu-toolkit is a Ruby gem. This means you can install it with one simple
+command: 
+
+    gem install qemu-toolkit
+    
+For full installation instructions, please see qemu-toolkit-install(7). 
+
+## CONTRIBUTE
+
+This project is hosted on
+[bitbucket](https://bitbucket.org/kschiess/qemu-toolkit/src). An issue tracker
+is available at
+[bitbucket](https://bitbucket.org/kschiess/qemu-toolkit/issues).
+
+We value all contributions, provided they
+
+ * are tested and have a clear rationale
+ * are generally useful
+ * come as a clean changeset (pull request or email patch)
+
+Discussion regarding this project via 'qemutoolkit' mailing list. Subscribe by
+sending any kind of message to this
+[address](mailto:qemutoolkit@librelist.com).
+
+## SEE ALSO
+
+qemu-toolkit-overview(7), qemu-toolkit-install(7),
+qemu-toolkit-configuration(7), storadm(1), vmadm(1), README(7)
+
+## AUTHORS
+
+Copyright (c) 2012 Kaspar Schiess. 
+
+## COPYRIGHT
+
+This tool is under a MIT license. Please see the LICENSE file in the original
+source.

data/doc/README.7

@@ -0,0 +1,55 @@
+.\" generated with Ronn/v0.7.3
+.\" http://github.com/rtomayko/ronn/tree/0.7.3
+.
+.TH "QEMU\-TOOLKIT" "7" "November 2012" "" "qemu-toolkit"
+.
+.SH "NAME"
+\fBqemu\-toolkit\fR \- A toolkit for running qemu on Illumos / OmniOS
+.
+.SH "SYNOPSIS"
+qemu\-toolkit is a small set of scripts to control QEMU kvm virtualised machines on a set of illumos hosts\. Have a look at \'storadm\' and \'vmadm\' \- inline help will show you the possibilities\.
+.
+.SH "INSTALLATION"
+qemu\-toolkit is a Ruby gem\. This means you can install it with one simple command:
+.
+.IP "" 4
+.
+.nf
+
+gem install qemu\-toolkit
+.
+.fi
+.
+.IP "" 0
+.
+.P
+For full installation instructions, please see qemu\-toolkit\-install(7)\.
+.
+.SH "CONTRIBUTE"
+This project is hosted on bitbucket \fIhttps://bitbucket\.org/kschiess/qemu\-toolkit/src\fR\. An issue tracker is available at bitbucket \fIhttps://bitbucket\.org/kschiess/qemu\-toolkit/issues\fR\.
+.
+.P
+We value all contributions, provided they
+.
+.IP "\(bu" 4
+are tested and have a clear rationale
+.
+.IP "\(bu" 4
+are generally useful
+.
+.IP "\(bu" 4
+come as a clean changeset (pull request or email patch)
+.
+.IP "" 0
+.
+.P
+Discussion regarding this project via \'qemutoolkit\' mailing list\. Subscribe by sending any kind of message to this address \fImailto:qemutoolkit@librelist\.com\fR\.
+.
+.SH "SEE ALSO"
+qemu\-toolkit\-overview(7), qemu\-toolkit\-install(7), qemu\-toolkit\-configuration(7), storadm(1), vmadm(1), README(7)
+.
+.SH "AUTHORS"
+Copyright (c) 2012 Kaspar Schiess\.
+.
+.SH "COPYRIGHT"
+This tool is under a MIT license\. Please see the LICENSE file in the original source\.

data/doc/README.md

@@ -0,0 +1,47 @@
+# qemu-toolkit(7) -- A toolkit for running qemu on Illumos / OmniOS
+
+## SYNOPSIS
+
+qemu-toolkit is a small set of scripts to control QEMU kvm virtualised
+machines on a set of illumos hosts. Have a look at 'storadm' and 
+'vmadm' - inline help will show you the possibilities.
+
+## INSTALLATION
+
+qemu-toolkit is a Ruby gem. This means you can install it with one simple
+command: 
+
+    gem install qemu-toolkit
+    
+For full installation instructions, please see qemu-toolkit-install(7). 
+
+## CONTRIBUTE
+
+This project is hosted on
+[bitbucket](https://bitbucket.org/kschiess/qemu-toolkit/src). An issue tracker
+is available at
+[bitbucket](https://bitbucket.org/kschiess/qemu-toolkit/issues).
+
+We value all contributions, provided they
+
+ * are tested and have a clear rationale
+ * are generally useful
+ * come as a clean changeset (pull request or email patch)
+
+Discussion regarding this project via 'qemutoolkit' mailing list. Subscribe by
+sending any kind of message to this
+[address](mailto:qemutoolkit@librelist.com).
+
+## SEE ALSO
+
+qemu-toolkit-overview(7), qemu-toolkit-install(7),
+qemu-toolkit-configuration(7), storadm(1), vmadm(1), README(7)
+
+## AUTHORS
+
+Copyright (c) 2012 Kaspar Schiess. 
+
+## COPYRIGHT
+
+This tool is under a MIT license. Please see the LICENSE file in the original
+source.

data/doc/index.txt

@@ -0,0 +1 @@
+README(7)     README.7

data/doc/qemu-toolkit-configuration.7

@@ -0,0 +1,196 @@
+.\" generated with Ronn/v0.7.3
+.\" http://github.com/rtomayko/ronn/tree/0.7.3
+.
+.TH "QEMU\-TOOLKIT\-CONFIGURATION" "7" "November 2012" "" "qemu-toolkit"
+.
+.SH "NAME"
+\fBqemu\-toolkit\-configuration\fR \- configuration for qemu\-toolkit
+.
+.SH "SYNTAX"
+The tool \fBvmadm\fR reads all files ending in \fB\.rb\fR from \fB/etc/qemu\-toolkit\fR on startup\. It expects these Ruby scripts to define virtual machines using the syntax defined below\.
+.
+.SS "basic vm definition"
+A virtual machine definition is written in a Ruby\-DSL and looks like this:
+.
+.IP "" 4
+.
+.nf
+
+virtual_machine "myvm" do
+  # Options go here! You\'d need at least one disk to start\.
+end
+.
+.fi
+.
+.IP "" 0
+.
+.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:
+.
+.IP "" 4
+.
+.nf
+
+def lan name, mac
+  virtual_machine(name) do
+    nic \'eth0\', macaddr: mac, via: \'lan0\'
+  end
+end
+
+# Allows for very short VM definitions:
+lan \'vm1\', \'1:8:20:52:a6:7e\'
+.
+.fi
+.
+.IP "" 0
+.
+.SS "available options"
+Here\'s a list of configuration options within the virtual_machine declaration:
+.
+.TP
+cpus \fINUMBER\fR
+Configures the number of SMP cpus simulated to the guest system\. You should not configure more SMP cpus than you have physical CPU cores available\.
+.
+.IP "" 4
+.
+.nf
+
+# configures 4 SMP cpus
+cpus 4
+.
+.fi
+.
+.IP "" 0
+
+.
+.TP
+disk \fIDEVICE_PATH\fR
+Add a disk drive to the guest system\. \fIDEVICE_PATH\fR should be the quoted full path to a block device\.
+.
+.IP
+This is a macro that will define a \fBvirtio\fR\-device and automatically number your drives from 0 to N\. If you\'re looking for more immediate control over qemu options, use the \fBdrive\fR\-option\.
+.
+.IP "" 4
+.
+.nf
+
+# Use a zvol block device
+disk \'/dev/zvol/dsk/pool1/myvm/disk1\'
+.
+.fi
+.
+.IP "" 0
+
+.
+.TP
+drive \fIOPTIONS\fR
+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 \fBdisk\fR) For the full list of options, please refer to the QEMU documentation \fIhttp://qemu\.weilnetz\.de/qemu\-doc\.html\fR\.
+.
+.IP "" 4
+.
+.nf
+
+# Manual drive configuration:
+drive if: \'floppy\', file: \'floppy\.dsk\'
+.
+.fi
+.
+.IP "" 0
+
+.
+.TP
+net \fITYPE\fR, \fIOPTIONS\fR
+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 \fBnic\fR below:
+.
+.IP "" 4
+.
+.nf
+
+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\'
+.
+.fi
+.
+.IP "" 0
+
+.
+.TP
+nic \fINAME\fR, \fIOPTIONS\fR
+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 \fBvia:\fR option here\.
+.
+.IP
+The \fBvia:\fR option takes either physical links or etherstub switches as value\. You can also specify a VLAN tag, separated by a colon\. (ie: e1000g0:4)
+.
+.IP
+nic \fBmodel:\fR will default to \fBvirtio\fR\.
+.
+.IP
+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 \fBnic\fR, this is what you\'ll get\.
+.
+.IP "" 4
+.
+.nf
+
+# Create eth0 interface with given mac address via \'igb1\'\.
+nic \'eth0\', macaddr: \'2:8:20:52:a6:7e\', via: \'igb1\'
+.
+.fi
+.
+.IP "" 0
+
+.
+.TP
+ram \fIMEGABYTES\fR
+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)
+.
+.IP "" 4
+.
+.nf
+
+# One gigabyte of RAM should be enough for everyone\. (default)
+ram 1024
+.
+.fi
+.
+.IP "" 0
+
+.
+.TP
+vnc \fIPORT\fR
+Enables VNC server on port \fIPORT\fR\. 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 \fBvmadm console\fR or connect directly to the unix socket using socat\.
+.
+.IP "" 4
+.
+.nf
+
+# Make vnc listen on a given port: (5900 + display = tcp/ip port)
+vnc_display 0
+.
+.fi
+.
+.IP "" 0
+
+.
+.TP
+extra_arg \fIARGUMENT\fR
+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\.
+.
+.IP
+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\.
+.
+.IP "" 4
+.
+.nf
+
+# Arguments that are appended to the qemu launch command line:
+extra_arg \'\-foo\'
+.
+.fi
+.
+.IP "" 0
+
+.
+.SH "SEE ALSO"
+qemu\-toolkit\-overview(7), qemu\-toolkit\-install(7), qemu\-toolkit\-configuration(7), storadm(1), vmadm(1), README(7)

data/doc/qemu-toolkit-configuration.7.ronn

@@ -0,0 +1,126 @@
+# qemu-toolkit-configuration(7) -- configuration for qemu-toolkit
+
+## SYNTAX
+
+The tool `vmadm` reads all files ending in `.rb` from `/etc/qemu-toolkit` on
+startup. It expects these Ruby scripts to define virtual machines using the 
+syntax defined below. 
+
+### basic vm definition
+
+A virtual machine definition is written in a Ruby-DSL and looks like this: 
+
+    virtual_machine "myvm" do
+      # Options go here! You'd need at least one disk to start.
+    end
+
+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: 
+
+    def lan name, mac
+      virtual_machine(name) do
+        nic 'eth0', macaddr: mac, via: 'lan0'
+      end
+    end
+    
+    # Allows for very short VM definitions:
+    lan 'vm1', '1:8:20:52:a6:7e'
+
+### available options
+
+Here's a list of configuration options within the virtual_machine declaration:
+
+  * cpus <NUMBER>: 
+    Configures the number of SMP cpus simulated to the guest system. 
+    You should not configure more SMP cpus than you have physical CPU cores
+    available. 
+    
+        # configures 4 SMP cpus
+        cpus 4      
+
+  * disk <DEVICE_PATH>: 
+    Add a disk drive to the guest system. <DEVICE_PATH> should be the 
+    quoted full path to a block device. 
+    
+    This is a macro that will define a `virtio`-device and automatically number
+    your drives from 0 to N. If you're looking for more immediate control
+    over qemu options, use the `drive`-option.
+    
+        # Use a zvol block device
+        disk '/dev/zvol/dsk/pool1/myvm/disk1'
+
+  * drive <OPTIONS>:
+    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 `disk`) For the full list of options, please
+    refer to the [QEMU documentation](http://qemu.weilnetz.de/qemu-doc.html).
+    
+        # Manual drive configuration:
+        drive if: 'floppy', file: 'floppy.dsk'
+        
+  * net <TYPE>, <OPTIONS>:
+    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 `nic`
+    below: 
+      
+        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'
+
+  
+  * nic <NAME>, <OPTIONS>:
+    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 `via:`
+    option here. 
+    
+    The `via:` option takes either physical links or etherstub switches as 
+    value. 
+    You can also specify a VLAN tag, separated by a colon. (ie: e1000g0:4)
+    
+    nic `model:` will default to `virtio`.
+    
+    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 `nic`, this is what you'll get. 
+    
+        # Create eth0 interface with given mac address via 'igb1'.
+        nic 'eth0', macaddr: '2:8:20:52:a6:7e', via: 'igb1'
+
+  * ram <MEGABYTES>: 
+    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)
+    
+        # One gigabyte of RAM should be enough for everyone. (default)
+        ram 1024
+    
+  * vnc <PORT>:
+    Enables VNC server on port <PORT>. 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 `vmadm
+    console` or connect directly to the unix socket using socat.
+    
+        # Make vnc listen on a given port: (5900 + display = tcp/ip port)
+        vnc_display 0
+
+  * extra_arg <ARGUMENT>:
+    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. 
+    
+    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. 
+    
+        # Arguments that are appended to the qemu launch command line: 
+        extra_arg '-foo'
+    
+## SEE ALSO
+
+qemu-toolkit-overview(7), qemu-toolkit-install(7),
+qemu-toolkit-configuration(7), storadm(1), vmadm(1), README(7)

data/doc/qemu-toolkit-install.7

@@ -0,0 +1,224 @@
+.\" generated with Ronn/v0.7.3
+.\" http://github.com/rtomayko/ronn/tree/0.7.3
+.
+.TH "QEMU\-TOOLKIT\-INSTALL" "7" "November 2012" "" "qemu-toolkit"
+.
+.SH "NAME"
+\fBqemu\-toolkit\-install\fR \- installations instructions for the qemu\-toolkit
+.
+.SH "PREREQUISITES"
+For this to run, you need at least one physical host running OmniOS \fIhttp://omnios\.omniti\.com/\fR or another Illumos \fIhttps://en\.wikipedia\.org/wiki/Illumos\fR\-based distro\. The host needs to support VT/x extensions to be able to run KVM\-based virtualisation\. Also, some basic working knowledge of Illumos is of help\.
+.
+.SH "INSTALLATION"
+These instructions assume that you install on a clean OmniOS machine\. If you use another distribution, your mileage may vary\. If you have first\-hand experience on other distributions of Illumos, we\'d be interested to hear from you!
+.
+.SS "RVM & Ruby"
+Install packages needed to build Ruby:
+.
+.IP "" 4
+.
+.nf
+
+pkg install git autoconf gnu\-m4 gnu\-make gcc\-3 gnu\-patch \e
+lint system/header header\-math gnu\-coreutils readline \e
+gnu\-binutils gnu\-tar developer/linker
+.
+.fi
+.
+.IP "" 0
+.
+.P
+Then make sure that you have \fB/usr/sfw/bin\fR in your PATH and that your linker is functional\.
+.
+.P
+Install YAML:
+.
+.IP "" 4
+.
+.nf
+
+wget http://pyyaml\.org/download/libyaml/yaml\-0\.1\.4\.tar\.gz
+tar xzvf yaml\-0\.1\.4\.tar\.gz
+cd yaml\-0\.1\.4
+\./configure \-\-prefix=/usr
+make
+make install
+.
+.fi
+.
+.IP "" 0
+.
+.P
+Then Ruby (via RVM):
+.
+.IP "" 4
+.
+.nf
+
+curl \-L https://get\.rvm\.io | bash \-s stable \-\-ruby
+.
+.fi
+.
+.IP "" 0
+.
+.P
+Please see the RVM website \fIhttps://rvm\.io/\fR for more information\.
+.
+.SS "\'socat\'"
+socat is a tool that connects different types of sockets together\. The qemu\-toolkit toolchain uses it to make VNC and VM monitor available\.
+.
+.IP "" 4
+.
+.nf
+
+wget \-\-no\-check\-certificate http://bit\.ly/TwNMrJ \-O socat\-1\.7\.1\.3\.tar\.gz
+tar xzvf socat\-1\.7\.1\.3\.tar\.gz
+cd socat\-1\.7\.1\.3
+# PATCH for this to work: cat patch\.txt | patch
+\./configure
+make
+make install
+.
+.fi
+.
+.IP "" 0
+.
+.P
+Note that the above installation only succeeds if you patch socat using this patch:
+.
+.IP "" 4
+.
+.nf
+
+\-\-\- sysincludes\.h\.orig  2012\-09\-03 16:59:09\.351904279 +0000
++++ sysincludes\.h       2012\-09\-03 16:59:54\.388720160 +0000
+@@ \-131,6 +131,8 @@
+ #include <netpacket/packet\.h>
+ #endif
+ #if HAVE_NETINET_IF_ETHER_H
++#include <net/if\.h>
++#include <netinet/in\.h>
+ #include <netinet/if_ether\.h>
+ #endif
+ #if HAVE_LINUX_IF_TUN_H
+.
+.fi
+.
+.IP "" 0
+.
+.SS "iSCSI target"
+If you want to use the machine as iSCSI target (as a storage provider), you\'ll need to do at least this:
+.
+.IP "" 4
+.
+.nf
+
+pkg install network/iscsi/target
+svcadm enable \-r svc:/network/iscsi/target:default
+.
+.fi
+.
+.IP "" 0
+.
+.P
+The tools expect a target portal group named \fBfrontend\fR\. To create it, use something like the following command, where \fIIP\fR must be an TCP/IP address of the host you\'re doing this for:
+.
+.IP "" 4
+.
+.nf
+
+itadm create\-tpg frontend IP
+.
+.fi
+.
+.IP "" 0
+.
+.SS "QEMU / KVM"
+For qemu to work properly, you must make sure that you have at least as much swap space as you have RAM\. Default configuration only gives you 4GB of swap\. To fix this, do something like the following: (assumes that you\'ve got 30GB of RAM)
+.
+.IP "" 4
+.
+.nf
+
+zfs set volsize=30G rpool/swap
+.
+.fi
+.
+.IP "" 0
+.
+.P
+Also, perhaps obviously, you will need to load the kvm kernel driver\. This is accomplished by
+.
+.IP "" 4
+.
+.nf
+
+add_drv kvm
+.
+.fi
+.
+.IP "" 0
+.
+.P
+You will want to reboot the machine after these two steps for two reasons: Sometimes loading \fBkvm\fR interferes with reboot behaviour, you\'ll want to know that before you continue\. And swap resizing takes effect on reboot only\.
+.
+.SS "qemu\-toolkit"
+Once you\'ve done all this, you\'re ready to install \fBqemu\-toolkit\fR\. Simply:
+.
+.IP "" 4
+.
+.nf
+
+gem install qemu\-toolkit
+.
+.fi
+.
+.IP "" 0
+.
+.P
+You should now have \fBvmadm\fR and \fBstoradm\fR in your path\.
+.
+.SH "FIRST STEPS"
+Create a block device for your virtual machine\. Assuming you want to create it on \fIPOOL\fR:
+.
+.IP "" 4
+.
+.nf
+
+storadm create POOL/myvm 10G
+.
+.fi
+.
+.IP "" 0
+.
+.P
+This should create a dataset called \fIPOOL\fR\fB/myvm\fR and a subordinate zvol called \'disk1\'\. Let\'s connect a virtual machine to that disk:
+.
+.IP "" 4
+.
+.nf
+
+vmadm create myvm
+.
+.fi
+.
+.IP "" 0
+.
+.P
+This will create a configuration file called \fB/etc/qemu\-toolkit/myvm\.rb\fR\. Feel free to edit this\. Once you\'ve customized it to your liking, start the virtual machine and boot from an \fIISO\fR image:
+.
+.IP "" 4
+.
+.nf
+
+vmadm start myvm \-\-bootiso=ISO
+.
+.fi
+.
+.IP "" 0
+.
+.P
+If you\'re interested in configuring your virtual machine (qemu), please see qemu\-toolkit\-configuration(7)\.
+.
+.SH "SEE ALSO"
+qemu\-toolkit\-overview(7), qemu\-toolkit\-install(7), qemu\-toolkit\-configuration(7), storadm(1), vmadm(1), README(7)