Commits

Kaspar Schiess committed 0d33610

Project readme

  • Participants
  • Parent commits b445ca9

Comments (0)

Files changed (4)

-# qemu-toolkit(1) -- A toolkit for running qemu on Illumos / OmniOS
+# qemu-toolkit(7) -- A toolkit for running qemu on Illumos / OmniOS
 
 ## SYNOPSIS
 
 machines on a set of illumos hosts. Have a look at 'storadm' and 
 'vmadm' - inline help will show you the possibilities.
 
-## OVERVIEW
-
-This is the toolkit for running qemu on OmniOS/Illumos. Features:
-
-  * Run VMs based on local zvols 
-  * Run VMs based on iSCSI targets
-  * Fully use QEMUs options (through a nifty Ruby DSL)
-  * Automatic network configuration based on vnics
-  * Using vnics confined to VLANs
-  * 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
+## INSTALLATION
 
-Using this toolkit, you can deploy your virtual machines in one of two ways: 
+qemu-toolkit is a Ruby gem. This means you can install it with one simple
+command: 
 
-  * 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
+    gem install qemu-toolkit
     
-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. 
+For full installation instructions, please see qemu-toolkit-install(7). 
 
-### SAN-style
+## CONTRIBUTE
 
-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: 
+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).
 
-    B $ storadm create pool1/foo 10G
-    B $ storadm export pool1/foo
-    
-    A $ vmadm create foo
-    # Edit foo.rb at this point to include a valid iqn + IP pair for host B
-    A $ vmadm start foo --bootiso=installation-disk.iso
+We value all contributions, provided they
 
-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.
+ * are tested and have a clear rationale
+ * are generally useful
+ * come as a clean changeset (pull request or email patch)
 
-## 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. 
+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), storadm(1), vmadm(1)
 
-
 ## AUTHORS
 
-Copyright (c) 2012 Kaspar Schiess. Distribution under a MIT license:
-
-Permission is hereby granted, free of charge, to any person
-obtaining a copy of this software and associated documentation
-files (the "Software"), to deal in the Software without
-restriction, including without limitation the rights to use,
-copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the
-Software is furnished to do so, subject to the following
-conditions:
-
-The above copyright notice and this permission notice shall be
-included in all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
-EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
-OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
-NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
-HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
-WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
-FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
-OTHER DEALINGS IN THE SOFTWARE.
+Copyright (c) 2012 Kaspar Schiess. 
 
+## COPYRIGHT
 
+This tool is under a MIT license. Please see the LICENSE file in the original
+source.

doc/qemu-toolkit-install.7.ronn

Empty file added.

doc/qemu-toolkit-overview.7.ronn

 # qemu-toolkit-overview(7) -- Configuration overview for qemu-toolkit
 
+## OVERVIEW
+
+This is the toolkit for running qemu on OmniOS/Illumos. Features:
+
+  * Run VMs based on local zvols 
+  * Run VMs based on iSCSI targets
+  * Fully use QEMUs options (through a nifty Ruby DSL)
+  * Automatic network configuration based on vnics
+  * Using vnics confined to VLANs
+  * 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: 
+
+    B $ storadm create pool1/foo 10G
+    B $ storadm export pool1/foo
+    
+    A $ vmadm create foo
+    # Edit foo.rb at this point to include a valid iqn + IP pair for host B
+    A $ 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.
+
+## 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. 
+
 ## SEE ALSO
 
 qemu-toolkit-overview(7), storadm(1), vmadm(1)
   
   system %Q(ronn --style toc --html \
     ../doc/qemu-toolkit-overview.7.ronn ../doc/storadm.1.ronn \
-    ../doc/vmadm.1.ronn ../doc/README)
+    ../doc/vmadm.1.ronn ../doc/README ../doc/qemu-toolkit-install.7.ronn \
+    )
 
   Dir['../doc/*.html'].each do |file|
     FileUtils.mv file, '.'