qemu-toolkit 0.2.18 → 0.3.0

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

@@ -0,0 +1,136 @@
+# qemu-toolkit-install(7) -- installations instructions for the qemu-toolkit
+
+## PREREQUISITES
+
+For this to run, you need at least one physical host running
+[OmniOS](http://omnios.omniti.com/) or another
+[Illumos](https://en.wikipedia.org/wiki/Illumos)-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.
+
+## 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!
+
+### RVM & Ruby 
+
+Install packages needed to build Ruby: 
+  
+    pkg install git autoconf gnu-m4 gnu-make gcc-3 gnu-patch \
+    lint system/header header-math gnu-coreutils readline \
+    gnu-binutils gnu-tar developer/linker
+      
+Then make sure that you have `/usr/sfw/bin` in your PATH and that your
+linker is functional.
+
+Install YAML: 
+
+    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
+    
+Then Ruby (via RVM): 
+
+    curl -L https://get.rvm.io | bash -s stable --ruby
+    
+Please see the RVM [website](https://rvm.io/) for more information.
+
+### '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. 
+
+    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
+    
+Note that the above installation only succeeds if you patch socat using this
+patch: 
+
+    --- 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
+       
+### iSCSI target
+
+If you want to use the machine as iSCSI target (as a storage provider), you'll
+need to do at least this: 
+
+    pkg install network/iscsi/target
+    svcadm enable -r svc:/network/iscsi/target:default
+    
+The tools expect a target portal group named `frontend`. To create it, use 
+something like the following command, where <IP> must be an TCP/IP address 
+of the host you're doing this for: 
+
+    itadm create-tpg frontend IP
+    
+### 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)
+
+    zfs set volsize=30G rpool/swap
+    
+Also, perhaps obviously, you will need to load the kvm kernel driver. This is
+accomplished by 
+
+    add_drv kvm
+    
+You will want to reboot the machine after these two steps for two reasons: 
+Sometimes loading `kvm` interferes with reboot behaviour, you'll want to know 
+that before you continue. And swap resizing takes effect on reboot only.
+
+### qemu-toolkit
+
+Once you've done all this, you're ready to install `qemu-toolkit`. Simply: 
+
+    gem install qemu-toolkit
+    
+You should now have `vmadm` and `storadm` in your path. 
+
+## FIRST STEPS
+
+Create a block device for your virtual machine. Assuming you want to create 
+it on <POOL>: 
+
+    storadm create POOL/myvm 10G
+    
+This should create a dataset called <POOL>`/myvm` and a subordinate zvol 
+called 'disk1'. Let's connect a virtual machine to that disk: 
+
+    vmadm create myvm
+    
+This will create a configuration file called `/etc/qemu-toolkit/myvm.rb`. 
+Feel free to edit this. Once you've customized it to your liking, start the
+virtual machine and boot from an <ISO> image: 
+
+    vmadm start myvm --bootiso=ISO
+  
+If you're interested in configuring your virtual machine (qemu), please see
+qemu-toolkit-configuration(7). 
+    
+## SEE ALSO
+
+qemu-toolkit-overview(7), qemu-toolkit-install(7),
+qemu-toolkit-configuration(7), storadm(1), vmadm(1), README(7)

data/doc/qemu-toolkit-overview.7

@@ -0,0 +1,122 @@
+.\" generated with Ronn/v0.7.3
+.\" http://github.com/rtomayko/ronn/tree/0.7.3
+.
+.TH "QEMU\-TOOLKIT\-OVERVIEW" "7" "November 2012" "" "qemu-toolkit"
+.
+.SH "NAME"
+\fBqemu\-toolkit\-overview\fR \- architecture and philosophy of qemu\-toolkit
+.
+.SH "OVERVIEW"
+This is a toolkit for running qemu on OmniOS/Illumos\. Features:
+.
+.IP "\(bu" 4
+VMs based on local zvols
+.
+.IP "\(bu" 4
+VMs based on iSCSI targets
+.
+.IP "\(bu" 4
+Full access to QEMUs options (through a nifty Ruby DSL)
+.
+.IP "\(bu" 4
+Automatic vnic creation, supports VLAN tags
+.
+.IP "\(bu" 4
+Secure VNC channel through unix socket
+.
+.IP "\(bu" 4
+Access to VM monitor and serial console
+.
+.IP "" 0
+.
+.P
+Here\'s a sample configuration file:
+.
+.IP "" 4
+.
+.nf
+
+virtual_machine "vm_name" do
+  # Network configuration: vnic via igb1
+  nic \'eth0\', macaddr: \'2:8:20:52:a6:7e\', via: \'igb1\'
+
+  # Disks: via iSCSI iqn
+  iscsi_target \'iqn\.2010\-01\.com\.qemu\-toolkit:vm_name\', "10\.0\.30\.1"
+
+  # 4 SMP CPUs\.
+  cpus 4
+end
+.
+.fi
+.
+.IP "" 0
+.
+.P
+On\-disk layout is as follows:
+.
+.IP "" 4
+.
+.nf
+
+foo                 base zfs dataset
+foo/disk1           first disk, zvol block device
+foo/disk2           second disk, zvol block device
+.
+.fi
+.
+.IP "" 0
+.
+.SH "DEPLOYMENT OPTIONS"
+Using this toolkit, you can deploy your virtual machines in one of two ways:
+.
+.IP "\(bu" 4
+All\-local, using zvols
+.
+.IP "\(bu" 4
+SAN\-style, using iSCSI based block devices mapping to zvols
+.
+.IP "" 0
+.
+.SS "Local ZVOLs"
+In this architectural style, you use both tools (storadm(1) and vmadm(1)) on the same machine\. To create a virtual machine from scratch, you would use the following sequence of commands:
+.
+.IP "" 4
+.
+.nf
+
+$ storadm create pool1/foo 10G
+$ vmadm create foo
+$ vmadm start foo \-\-bootiso=installation\-disk\.iso
+.
+.fi
+.
+.IP "" 0
+.
+.P
+This would create a base dataset pool1/foo with one 10G block device as root disk\. It then creates a file \fBfoo\.rb\fR below \fB/etc/qemu\-toolkit/\fR that defines base attributes for the virtual machine\. Finally, starting the machine using the \fB\-\-bootiso\fR parameter would allow you to install a base system to the virtual machine\.
+.
+.SS "SAN\-style"
+Here you use two machines, one as storage host and one as VM host\. The virtual machines run on host A, but all storage is provided for by host B\. Here\'s a typical sequence of commands to create a virtual machine from scratch in this scenario:
+.
+.IP "" 4
+.
+.nf
+
+Machine B:
+$ storadm create pool1/foo 10G
+$ storadm export pool1/foo
+
+Machine A
+$ vmadm create foo
+# Edit foo\.rb at this point to include a valid iqn + IP pair for host B
+$ vmadm start foo \-\-bootiso=installation\-disk\.iso
+.
+.fi
+.
+.IP "" 0
+.
+.P
+This assumes that you\'ve got iSCSI set up on both machines\. (initiator on A, target on B) While this configuration is certainly more complex than the all\-local one above, it is also more flexible to administer\.
+.
+.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-overview.7.ronn

@@ -0,0 +1,82 @@
+# qemu-toolkit-overview(7) -- architecture and philosophy of qemu-toolkit
+
+## OVERVIEW
+
+This is a toolkit for running qemu on OmniOS/Illumos. Features:
+
+  * VMs based on local zvols 
+  * VMs based on iSCSI targets
+  * Full access to QEMUs options (through a nifty Ruby DSL)
+  * Automatic vnic creation, supports VLAN tags
+  * Secure VNC channel through unix socket
+  * Access to VM monitor and serial console
+  
+  
+Here's a sample configuration file: 
+
+    virtual_machine "vm_name" do
+      # Network configuration: vnic via igb1
+      nic 'eth0', macaddr: '2:8:20:52:a6:7e', via: 'igb1'
+      
+      # Disks: via iSCSI iqn
+      iscsi_target 'iqn.2010-01.com.qemu-toolkit:vm_name', "10.0.30.1"
+      
+      # 4 SMP CPUs.
+      cpus 4
+    end
+
+On-disk layout is as follows: 
+
+    foo                 base zfs dataset
+    foo/disk1           first disk, zvol block device
+    foo/disk2           second disk, zvol block device
+    
+## DEPLOYMENT OPTIONS
+
+Using this toolkit, you can deploy your virtual machines in one of two ways: 
+
+  * All-local, using zvols
+  * SAN-style, using iSCSI based block devices mapping to zvols
+  
+### Local ZVOLs
+
+In this architectural style, you use both tools (storadm(1) and vmadm(1)) on 
+the same machine. To create a virtual machine from scratch, you would use the
+following sequence of commands: 
+
+    $ storadm create pool1/foo 10G
+    $ vmadm create foo
+    $ vmadm start foo --bootiso=installation-disk.iso
+    
+This would create a base dataset pool1/foo with one 10G block device as root
+disk. It then creates a file `foo.rb` below `/etc/qemu-toolkit/` that defines
+base attributes for the virtual machine. Finally, starting the machine using
+the `--bootiso` parameter would allow you to install a base system to the virtual 
+machine. 
+
+### SAN-style
+
+Here you use two machines, one as storage host and one as VM host. The virtual
+machines run on host A, but all storage is provided for by host B. Here's a
+typical sequence of commands to create a virtual machine from scratch in this
+scenario: 
+
+    Machine B:
+    $ storadm create pool1/foo 10G
+    $ storadm export pool1/foo
+    
+    Machine A
+    $ vmadm create foo
+    # Edit foo.rb at this point to include a valid iqn + IP pair for host B
+    $ vmadm start foo --bootiso=installation-disk.iso
+
+This assumes that you've got iSCSI set up on both machines. (initiator on A, 
+target on B) While this configuration is certainly more complex than the
+all-local one above, it is also more flexible to administer.
+
+## SEE ALSO
+
+qemu-toolkit-overview(7), qemu-toolkit-install(7),
+qemu-toolkit-configuration(7), storadm(1), vmadm(1), README(7)
+
+

data/doc/storadm.1

@@ -0,0 +1,142 @@
+.\" generated with Ronn/v0.7.3
+.\" http://github.com/rtomayko/ronn/tree/0.7.3
+.
+.TH "STORADM" "1" "November 2012" "" "qemu-toolkit"
+.
+.SH "NAME"
+\fBstoradm\fR \- manages virtual machine storage
+.
+.SH "SYNOPSIS"
+\fBstoradm\fR [\-h]
+.
+.br
+\fBstoradm list\fR
+.
+.br
+\fBstoradm create\fR [\-v] \fIname\fR
+.
+.br
+\fBstoradm clone\fR [\-v] \fIname\fR \fItemplate\fR \fIversion\fR
+.
+.br
+\fBstoradm export\fR [\-v] \fIname\fR
+.
+.br
+\fBstoradm hide\fR [\-v] \fIname\fR
+.
+.br
+.
+.SH "DESCRIPTION"
+The \fBstoradm\fR command allows you to manage virtual machine storage all in one place\. It creates, clones and destroys storage spaces\. And if you want to separate storage machines from the hosts that run virtual machines (a SAN style setup), you can \- \fBstoradm\fR provides two subcommands for this setup\.
+.
+.P
+Virtual machine storage is based on ZFS and uses the following dataset layout:
+.
+.IP "" 4
+.
+.nf
+
+vm_name             # base dataset
+vm_name/disk1       # first block device (zvol)
+.
+.fi
+.
+.IP "" 0
+.
+.P
+These subcommands are defined:
+.
+.TP
+\fBstoradm list\fR
+Lists all virtual machine storage spaces on this machine\. For all storage spaces that have an iSCSI export, it lists the corresponding IQN\.
+.
+.TP
+\fBstoradm create\fR [\-v] \fIname\fR
+Creates a new storage space\. \fIname\fR should be a full zfs path to where you want to create the storage space, something like \fBpool1/foo\fR\.
+.
+.TP
+\fB\-v\fR
+Prints all commands as they are executed\.
+
+.
+.TP
+\fBstoradm clone\fR [\-v] \fIname\fR \fItemplate\fR \fIversion\fR
+Clones a new storage space from a template\. \fItemplate\fR refers to a storage space that has a recursive snapshot called \fIversion\fR\.
+.
+.TP
+\fB\-v\fR
+Prints all commands as they are executed\.
+
+.
+.TP
+\fBstoradm export\fR [\-v] \fIname\fR
+Creates an iSCSI export for the storage space\. All disks of the storage space are mapped to LUNs in the iSCSI target\.
+.
+.TP
+\fB\-v\fR
+Prints all commands as they are executed\.
+
+.
+.TP
+\fBstoradm hide\fR [\-v] \fIname\fR
+Hides a storage space by removing the previously created iSCSI export from the system\.
+.
+.TP
+\fB\-v\fR
+Prints all commands as they are executed\.
+
+.
+.SH "EXAMPLES"
+.
+.SS "Example 1 Creating a storage space"
+The following command creates an empty virtual machine storage space with one disk drive of 10GB\.
+.
+.IP "" 4
+.
+.nf
+
+# storadm create pool1/foo 10G
+.
+.fi
+.
+.IP "" 0
+.
+.SS "Example 2 Listing all available storage spaces"
+The following command lists all available storage spaces\.
+.
+.IP "" 4
+.
+.nf
+
+# storadm list
+pool1/foo
+.
+.fi
+.
+.IP "" 0
+.
+.SS "Example 3 Creating a base version and cloning it"
+The following commands snapshot an existing storage space called \fBpool1/template\fR with the version tag \fB0\.1\.0\fR\. A clone is then created based on that version of \fBpool1/template\fR\.
+.
+.IP "" 4
+.
+.nf
+
+# zfs snapshot \-r pool1/template@0\.1\.0
+# storadm clone my_vm pool1/template 0\.1\.0
+.
+.fi
+.
+.IP "" 0
+.
+.SH "BUGS"
+Only the unknown\.
+.
+.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/storadm.1.ronn

@@ -0,0 +1,101 @@
+
+# storadm(1) -- manages virtual machine storage
+
+## SYNOPSIS
+
+`storadm` [-h]<br>
+`storadm list`<br>
+`storadm create` [-v] <name><br>
+`storadm clone` [-v] <name> <template> <version><br>
+`storadm export` [-v] <name><br>
+`storadm hide` [-v] <name><br>
+
+## DESCRIPTION
+
+The `storadm` command allows you to manage virtual machine storage all in
+one place. It creates, clones and destroys storage spaces. And if you want
+to separate storage machines from the hosts that run virtual machines (a SAN 
+style setup), you can - `storadm` provides two subcommands for this setup.
+
+Virtual machine storage is based on ZFS and uses the following dataset
+layout: 
+
+    vm_name             # base dataset
+    vm_name/disk1       # first block device (zvol)
+    
+These subcommands are defined:
+    
+  * `storadm list`: 
+    Lists all virtual machine storage spaces on this machine. For all 
+    storage spaces that have an iSCSI export, it lists the corresponding 
+    IQN. 
+    
+  * `storadm create` [-v] <name>:
+    Creates a new storage space. <name> should be a full zfs path to where
+    you want to create the storage space, something like `pool1/foo`.
+    
+    * `-v`:
+      Prints all commands as they are executed.
+  
+  * `storadm clone` [-v] <name> <template> <version>:
+    Clones a new storage space from a template. <template> refers to a 
+    storage space that has a recursive snapshot called <version>. 
+  
+    * `-v`:
+      Prints all commands as they are executed.
+      
+  * `storadm export` [-v] <name>:
+    Creates an iSCSI export for the storage space. All disks of the storage
+    space are mapped to LUNs in the iSCSI target. 
+
+    * `-v`:
+      Prints all commands as they are executed.
+
+  * `storadm hide` [-v] <name>:
+    Hides a storage space by removing the previously created iSCSI export 
+    from the system. 
+    
+    * `-v`:
+      Prints all commands as they are executed.
+    
+## EXAMPLES
+
+### Example 1 Creating a storage space
+The following command creates an empty virtual machine storage space with one
+disk drive of 10GB.
+
+    # storadm create pool1/foo 10G
+
+### Example 2 Listing all available storage spaces
+
+The following command lists all available storage spaces.
+
+    # storadm list
+    pool1/foo     
+    
+### Example 3 Creating a base version and cloning it
+
+The following commands snapshot an existing storage space called 
+`pool1/template` with the version tag `0.1.0`. A clone is then created based
+on that version of `pool1/template`.
+
+    # zfs snapshot -r pool1/template@0.1.0
+    # storadm clone my_vm pool1/template 0.1.0
+                  
+## BUGS
+
+Only the unknown.
+
+## 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/vmadm.1

@@ -0,0 +1,116 @@
+.\" generated with Ronn/v0.7.3
+.\" http://github.com/rtomayko/ronn/tree/0.7.3
+.
+.TH "VMADM" "1" "November 2012" "" "qemu-toolkit"
+.
+.SH "NAME"
+\fBvmadm\fR \- manages qemu\-toolkit virtual machines
+.
+.SH "SYNOPSIS"
+\fBvmadm\fR [\-h]
+.
+.br
+\fBvmadm list\fR
+.
+.br
+\fBvmadm create\fR \fIname\fR
+.
+.br
+\fBvmadm start\fR [\-\-bootiso \fIiso_file\fR]\fIname\fR
+.
+.br
+\fBvmadm shutdown\fR \fIname\fR
+.
+.br
+\fBvmadm kill\fR \fIname\fR
+.
+.br
+\fBvmadm monitor\fR \fIname\fR
+.
+.br
+\fBvmadm vnc\fR \fIname\fR
+.
+.br
+\fBvmadm console\fR \fIname\fR
+.
+.br
+.
+.SH "DESCRIPTION"
+The \fBvmadm\fR command manages virtual machines\. A virtual machine is defined by using the \fBvirtual_machine\fR syntax in a file below \fB/etc/qemu\-toolkit\fR\. (see qemu\-toolkit\-configuration(7))
+.
+.TP
+\fBvmadm list\fR
+Lists all virtual machines that are defined on this system\.
+.
+.TP
+\fBvmadm create\fR \fIname\fR
+Creates a new virtual machine definition and fills it with sensible default values\.
+.
+.TP
+\fBvmadm start\fR \fIname\fR
+Starts a virtual machine using QEMU/KVM\.
+.
+.TP
+\fB\-\-bootiso\fR \fIiso_file\fR
+Boots the virtual machine once from virtual cdrom backed by the iso file given\. Upon reboot, the machine will use its first disk to boot\.
+
+.
+.TP
+\fBvmadm shutdown\fR \fIname\fR
+Sends the virtual machine a system/powerdown event\.
+.
+.TP
+\fBvmadm kill\fR \fIname\fR
+Immediately kills the virtual machine\.
+.
+.TP
+\fBvmadm monitor\fR \fIname\fR
+Enters an interactive monitor mode that controls the virtual machine\. The machine must be running for this to work\. Use Control+D to exit\.
+.
+.TP
+\fBvmadm vnc\fR \fIname\fR
+Connect the terminal to a VNC server that displays the console of the virtual machine\.
+.
+.TP
+\fBvmadm console\fR \fIname\fR
+Connects the terminal to the serial console of the virtual machine\. Note that this must be specially configured for most guest OSes\.
+.
+.SH "EXAMPLES"
+.
+.SS "Example 1 Boot a virtual machine"
+The following command starts the virtual machine and boots it from its first disk\.
+.
+.IP "" 4
+.
+.nf
+
+# vmadm start my_vm
+.
+.fi
+.
+.IP "" 0
+.
+.SS "Example 2 Install a virtual machine from ISO"
+The following command boots the virtual machine from a virtual cdrom\. The cdrom is backed by an ISO file called ubuntu\.iso\.
+.
+.IP "" 4
+.
+.nf
+
+# vmadm start my_vm \-\-bootiso ubuntu\.iso
+.
+.fi
+.
+.IP "" 0
+.
+.SH "BUGS"
+When using iscsi targets, you have to relaunch the vm twice to get it to start up\. We have code in place to work around this, but it is not effective\. Work to fix this is underway\.
+.
+.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\.