veewee 0.3.7 → 0.3.9

data/doc/build_hooks.md

@@ -0,0 +1,69 @@
+# -- Build Hooks --
+
+You can implement hooks in your machine definition to customize the build process.
+The following hooks are currently available:
+
+* `:before_create` before box is created
+* `:after_create` after box is created
+* `:after_up` after box is started
+* `:after_boot_sequence` after boot command sequence is executed
+* `:after_postinstall` after post-install files are executed
+* `:before_ssh` before each SSH login
+
+The hooks are triggered in `lib/veewee/provider/core/box/build.rb`
+
+* Hooks are defined under the `:hooks` key in the box definition hash in your `definition.rb`
+* Hooks must be instances of `Proc` (or respond to `call`)
+
+## -- Examples --
+
+### -- Upload arbitrary files --
+
+Sure you should use postinstall to copy and execute scripts.
+But if you want to copy arbitrary files to the guest you can do this in a hook.
+
+<pre>
+Veewee::Definition.declare({
+  hooks => {
+      :after_postinstall => Proc.new { definition.box.scp('/tmp/foo.txt', '/tmp/bar.txt') }
+  }
+})
+</pre>
+
+### -- Guarded SSH login --
+
+SSH login is triggered from a separate Thread.
+If SSH is available before the boot command sequence is finished
+and the account password is changed in the command sequence authentication may fail.
+
+Guarded SSH login using the `:before_ssh` hook:
+
+<pre>
+class MyHooks
+  def initialize(definition)
+    @definition = definition
+  end
+
+  def after_boot_sequence
+    puts "unlocked ssh. port is #{@definition.ssh_host_port}"
+    @ssh_enabled = true
+  end
+
+  def before_ssh
+    sleep 0.5 until @ssh_enabled
+  end
+end
+
+myhooks = Hooks.new(veewee_definition)
+
+Veewee::Definition.declare({
+  hooks => {
+      :after_boot_sequence => Proc.new { myhooks.after_boot_sequence },
+      :before_ssh => Proc.new { myhooks.before_ssh }
+  }
+})
+</pre>
+
+
+
+

data/doc/changes.md

@@ -0,0 +1,20 @@
+# Major Changes
+
+## Changes between v0.2 -> v0.3
+
+1. The `Veewee::Session.declare` is now _deprecated_ and you should use `Veewee::Definition.declare`.
+   'postinstall_files' prefixed with an _underscore_ are not executed by default:
+
+    ~~~ sh
+    .
+    ├── definitions
+    │   └── myubuntubox
+    │       ├── _postinstall.sh    # NOT executed
+    │       ├── postinstall_2.sh   # GETS executed
+    ~~~
+
+   You can enforce including or excluding files with the `--include` and `--exclude` flag when using the `build` command. This allows you to use different scripts for installing ruby or to disable the installation of puppet or chef.
+
+2. The default user of definitions is now `veewee` and not `vagrant`.
+   This is because on other VMs like `fusion` and `kvm`, there is no relationship with the `vagrant` user.
+   The `vagrant` user is created by the `vagrant.sh` script and not by the _preseed_ or _kickstart_ files.

data/doc/commands.md

@@ -0,0 +1,42 @@
+# Veewee Command Options
+
+You can choose from a few different command line options when executing Veewee.
+
+## Veewee with `bundle exec`
+
+Unless you've created an alias for `veewee`, always include the `bundle exec` prefix like this:
+
+    $ bundle exec veewee
+
+
+## Veewee without `bundle exec`
+
+For convenience, it's handy to create an alias for the `veewee` command so we don't have to type `bundle exec` any longer. 
+
+Add the alias `alias veewee='bundle exec veewee'` to your shell's default startup file (e.g. ~/.bash_profile):
+
+    echo "alias veewee='bundle exec veewee'" >> ~/.bash_profile
+
+**For Ubuntu:** Modify your ~/.profile instead of ~/.bash_profile.
+<br>**For Zsh:** Modify your ~/.zshrc file instead of ~/.bash_profile.
+
+After adding the alias described above you'll be able to use the shorthand `veewee` command:
+
+    $ veewee
+    
+
+## Veewee as a Vagrant Plugin
+
+You can also use Veewee as a [Vagrant plugin](http://docs.vagrantup.com/v2/plugins/index.html).
+
+As a plugin, Veewee introduces the subcommand `basebox` on top of the `vagrant` command:
+
+    $ vagrant basebox
+    Usage: vagrant basebox <command> [<args>]
+
+This allows you to use the `vagrant` command style, which may feel more natural if you're already used to working with Vagrant. Please see Veewee's [Vagrant](vagrant.md) doc for more details.
+
+
+## Up Next
+
+[Veewee Basics](basics.md) covers creating standard-issue boxes.

data/doc/customize.md

@@ -0,0 +1,145 @@
+# Customizing Definitions
+
+## Definition overview
+
+Definitions are stored under the `definitions/` directory relative to the current directory.
+
+    .
+    ├── definitions
+    │   └── myubuntubox
+    │       ├── <preseed.cfg, kickstart.cfg, ...>
+    │       ├── base.sh
+    │       ├── cleanup.sh
+    │       ├── chef.sh
+    │       ├── puppet.sh
+    │       ├── ruby.sh
+    │       ├── virtualbox.sh
+    │       └── ....sh
+    └── README.md
+
+The file `definition.rb` contains all the parameters to define the machine to be build (see below):
+
+* memory size
+* number of CPUs
+* user account and password
+* sudo command
+* shutdown command
+* URL and checksum to download the ISO
+
+When a new machine boots, it will typically fetch its initial configuration file over http from a _kickstart_ file defined in `kickstart_file`. These files are usually named `preseed.cfg` or `ks.cfg`.
+
+
+## Postinstall scripts
+
+You can define multiple postinstall files by providing an array of filenames within `definition.rb`, like so:
+
+    :postinstall_files => [ "postinstall.sh",  "postinstall_2.sh" ],
+
+Once the initial installation is done, Veewee will execute each postinstall `.sh` file on the machine in chronologic order (order found in :postinstall_files array).
+
+The main reason for splitting up the original `postinstall.sh` script into multiple files is to make the post-install steps as reusable and portable as possible for different virtualization systems and/or operating systems. For example, there is no need to install the Virtualbox Guest Additions on KVM or VMware Fusion.
+
+
+## Postinstall barebones
+
+A definition usually consists of at least these postinstall files:
+
+Filename        | Description
+----------------|-------------
+preseed.cfg     | Default options for the installer. See https://help.ubuntu.com/12.04/installation-guide/i386/preseed-using.html
+definition.rb   | Core definition of a box; like CPU, RAM, and the commands for the initial boot sequence
+postinstall.sh  | Steps that run _after_ installing the OS
+
+Newer definitions contain of even more files (they have broken `postinstall.sh` into multiple files) to get a finer separation of concerns for the installation.
+
+
+## Using ERB in files
+
+Add `.erb` to your files in a definition and they will get parsed accordingly.
+
+This is useful for generating kickstart, post-install at runtime.
+
+Thanks to __@mconigilaro__ for the contribution!
+
+
+## Configuring definition.rb
+
+The `definition.rb` file is the core definition file of each box. All crucial properties and postinstall scripts are defined here.
+
+The `boot_cmd_sequence` parameter allows you to override the initial commands (like keyboard layout) that are fired up in the first boot sequence.
+
+All other settings are used internally by Veewee, the virtualization provider, or simply for choosing the proper ISO:
+
+    Veewee::Definition.declare( {
+        :cpu_count => '1',
+        :memory_size=> '256',
+        :disk_size => '10140',
+        :disk_format => 'VDI',
+        :disk_variant => 'Standard',
+        :os_type_id => 'Ubuntu',
+        :iso_file => "ubuntu-12.10-server-i386.iso",
+        :iso_src => "http://releases.ubuntu.com/precise/ubuntu-12.10-server-i386.iso",
+        :iso_md5 => "3daaa312833a7da1e85e2a02787e4b66",
+        :iso_download_timeout => "1000",
+        :boot_wait => "10",
+        :boot_cmd_sequence => [
+            '<Esc><Esc><Enter>',
+            '/install/vmlinuz noapic preseed/url=http://%IP%:%PORT%/preseed.cfg ',
+            'debian-installer=en_US auto locale=en_US kbd-chooser/method=us ',
+            'hostname=%NAME% ',
+            'fb=false debconf/frontend=noninteractive ',
+            'console-setup/ask_detect=false console-setup/modelcode=pc105 console-setup/layoutcode=us ',
+            'initrd=/install/initrd.gz -- <Enter>'
+        ],
+        :kickstart_port => "7122",
+        :kickstart_timeout => "10000",
+        :kickstart_file => "preseed.cfg",
+        :ssh_login_timeout => "10000",
+        :ssh_user => "vagrant",
+        :ssh_password => "vagrant",
+        :ssh_key => "",
+        :ssh_host_port => "2222", :ssh_guest_port => "22",
+        :sudo_cmd => "echo '%p'|sudo -S sh '%f'",
+        :shutdown_cmd => "shutdown -H",
+        :postinstall_files => [ "postinstall.sh"],
+        :postinstall_timeout => "10000"
+    })
+
+**IMPORTANT:** If you change values directly in a template, be sure to run `bundle exec veewee <provider> undefine` to remove the old definition and then `bundle exec veewee <provider> define` again to copy the updated template files into the definition.
+
+If you are an experienced devops veteran and have enhanced template settings, please let us know why. We are very interested in improving Veewee's templates.
+
+
+## Provider `vm_options`
+
+Each provider _can_ take options that are specific the provider; more details will be available in each [provider](providers.md) doc but let's have a quick overview here:
+
+    Veewee::Definition.declare({
+        :cpu_count => '1',
+        :memory_size => '256',
+        :disk_size => '10140',
+        :disk_format => 'VDI',
+        :disk_variant => 'Standard',
+        # […]
+        :postinstall_files => [ "postinstall.sh" ],
+        :postinstall_timeout => "10000",
+        :kvm => {
+            :vm_options => [
+                'network_type' => 'bridge',
+                'network_bridge_name' => 'brlxc0'
+            ]
+        },
+        :virtualbox => {
+            :vm_options => [
+                'pae' => 'on',
+                'ioapic' => 'one'
+            ]
+        }
+    })
+
+This box will have `pae` and `ioapic` enabled with VirtualBox, and will use the `brlxc0` bridge with KVM (on libvirt).
+
+
+## Up Next
+
+[Veeweefile](veeweefile.md) can be used to define your own paths.

data/doc/fusion.md

@@ -1,2 +1,6 @@
-Coming Soon
+## VMware Fusion VM Provider
 
+To interact with [VMware (Fusion)](http://www.vmware.com/products/fusion/), we leverage (a currently patched) version of [Fission gem](https://github.com/thbishop/fission). This gem takes care of the heavy lifting.
+
+To interact with the screen, Veewee enables VNC on the created VMware Fusion machines
+and uses the [Ruby-VNC gem](http://code.google.com/p/ruby-vnc/) to send the keystrokes. Sending keystrokes too fast is a problem for this setup as well.

data/doc/installation.md

@@ -1,24 +1,105 @@
-This needs to be bulked out more, but for now, here is a basic guide to installing Veewee from source.
+# Veewee Installation
 
-First, if you are not using RVM, it's recommended that you do so as veewee will install in it's own gemset which keeps veewee and it's dependancies completely separate from your other Ruby gems.
+Before installing Veewee, please see the [Requirements](requirements.md) doc.
 
-RVM is available here: http://beginrescueend.com/
+## Install as a gem
 
-You can install it as follows:
+The Veewee project is moving quickly and the Rubygem might be outdated. Therefore it may be wise to install Veewee from source.
 
-    $ bash -s stable < <(curl -s https://raw.github.com/wayneeseguin/rvm/master/binscripts/rvm-installer)
-    $ source ~/.bash_profile
+    $ gem install veewee
 
-Now, install Ruby 1.9.2 using RVM:
+Projects that include the `veewee` gem can also benefit from utilizing Ruby version management (see below).
+
+
+## Install from source
+
+#### Installing Veewee without a Ruby version manager
+
+Installing Veewee without a Ruby version manager is **NOT** recommended:
+
+    $ cd <path_to_workspace>
+    $ git clone https://github.com/jedi4ever/veewee.git
+    $ cd veewee
+    $ gem install bundler
+    $ bundle install
+
+
+#### Installing Veewee with RVM
+
+With RVM already installed (see [Requirements](requirements.md)), ensure a ruby version that's supported by Veewee is available on your machine:
 
     $ rvm install 1.9.2
 
-Ok, now that we have RVM installed, you can now install Veewee.
+Clone the veewee project from source:
+
+    $ cd <path_to_workspace>
+    $ git clone https://github.com/jedi4ever/veewee.git
+    $ cd veewee
+
+Set the local gemset and ruby version within the current directory:
+
+    $ rvm use 1.9.2@veewee --create
+
+Run `bundle install` to install Gemfile dependencies for our local gemset:
+
+    $ gem install bundler
+    $ bundle install
+
 
-When you cd into the veewee directory, rvm should automatically read the .rvmrc file and prompt you to verify it - you can do so by pressing Y. This will then create a gemset for veewee.
+#### Installing Veewee with rbenv
 
+With rbenv already installed (see [Requirements](requirements.md)), ensure a ruby version that's supported by Veewee is available on your machine:
+
+    $ rbenv install 1.9.2-p320
+    $ rbenv rehash
+
+Clone the veewee project from source:
+
+    $ cd <path_to_workspace>
     $ git clone https://github.com/jedi4ever/veewee.git
     $ cd veewee
+
+Set the local ruby version within the current directory:
+
+    $ rbenv local 1.9.2-p320
+    $ rbenv rehash
+
+Run `bundle install` to install Gemfile dependencies for our selected ruby version:
+
     $ gem install bundler
+    $ rbenv rehash
     $ bundle install
+    $ rbenv rehash
+
+
+#### Install from source on Windows
+
+First, run `bundle install`.
+
+Then to run `veewee`, use `bundle exec veewee` or make a powershell alias to remember for you:
+
+    function Run-Veewee { bundle exec veewee }
+    Set-Alias veewee Run-Veewee
+
+
+#### Testing `kvm` while running from source
+
+By default the `:kvm` gem group is *disabled* to prevent the installation of `ruby-libvirt` on systems
+that don't need it. This is done by the file `.bundle/config`.
+
+If you do need it, run `bundle install --without restrictions` (restrictions is a dummy name).
+This will change the file `.bundle/config`, which is ignored by Git by default and must not be included in any commits. As this is a remembered option, you don't have to specify it every time.
+If you want to switch to the default behavior run `bundle install --without kvm` to enable restrictions.
+
+
+#### Running from source and using Ruby v1.8.7
+
+By default the :windows gem group is *enabled* . This loads the `em-winrm` gem - which is incompatible with 
+ruby-1.8.7 because it depends on the `gss-api` gem. To run from source you can execut `bundle install --without windows`
+
+This will change the file `.bundle/config`, which is ignored by Git per default and must not be included in any commits. If you want to switch to the default behavior run `bundle install --without restrictions` to include it
+
+
+## Up Next
 
+[Veewee Command Options](commands.md) highlights various approaches for executing Veewee on the command line.

data/doc/kvm.md

@@ -1,28 +1,42 @@
-# KVM Provider
+## KVM Provider
 
-NOTE: Virtualbox doesn't like KVM to be enabled
+To interact with the [KVM](http://www.linux-kvm.org/) (Kernel-based Virtual Machine) provider, Veewee uses [libvirt support](http://libvirt.org/ruby/) provided through the [Fog gem](http://fog.io).
+
+To interact with the screen, Veewee enables VNC on the created KVM machines
+and uses the [Ruby-VNC gem](http://code.google.com/p/ruby-vnc/) to send the keystrokes. Sending keystrokes too fast is a problem for this setup as well.
+
+**NOTE:** VirtualBox doesn't like KVM to be enabled.
 
 ## Prerequisites
 
-To check if your kernel can run kvm :
+Depending on your operating system you may need to install packages for kvm,
+qemu and libvirt.
+
+If you have problems compiling the libvirt gem, check if you have the 'dev' parts installed too. 
+f.i ``apt-get install libvirt libvirt-dev``
+
+To check if your kernel can run kvm:
 
     # kvm_ok or kvm-ok command (on Ubuntu at least)
-    kvm_ok
+    $ kvm_ok
+    
     # or look for vmx or svm in /proc/cpuinfo
-    egrep '^flags.*(vmx|svm)' /proc/cpuinfo
+    $ egrep '^flags.*(vmx|svm)' /proc/cpuinfo
+
+The kernel modules needed are the following: `kvm`, `kvm_intel` or `kvm-amd`.
 
-The modules needed are the following : kvm, kvm_intel or kvm-amd.
+### Storage Pool
 
-You need to have at least one storage pool defined in libvirt. You can check all
-available storage pools with
+You need to have at least one storage pool defined in libvirt where your VM
+images will be stored. You can check all available storage pools with:
 
-    virsh pool-list
+    $ virsh pool-list
 
 If no storage pool is listed, you can create a new storage pool which saves all
-VM images in the directory /var/lib/libvirt/images with
+VM images in the directory /var/lib/libvirt/images with:
 
-    mkdir -p /var/lib/libvirt/images
-    cat > /tmp/pool.xml << EOF
+    $ mkdir -p /var/lib/libvirt/images
+    $ cat > /tmp/pool.xml << EOF
     <pool type="dir">
       <name>virtimages</name>
       <target>
@@ -31,56 +45,52 @@ VM images in the directory /var/lib/libvirt/images with
       </target>
     </pool>
     EOF
-    virsh pool-create /tmp/pool.xml
+    $ virsh pool-create /tmp/pool.xml
+
+### Network
 
 You need to have at least one network defined. You can check all available
-networks with
+networks with:
 
-    virsh net-list
+    $ virsh net-list
 
-If there is no default network, consult the documentation of your operating
-system to find out how to creat it.
+If there is no network, consult the documentation of your operating
+system to find out how to create it. More information can also be found in the
+[libvirt documentation](http://libvirt.org/formatdomain.html#elementsNICS).
 
 If you are using libvirt with a URI different than the default `qemu:///system`,
 you need to create a config file for fog.io. If your libvirt endpoint is
 accessible at `qemu+ssh://cloud@myhost.com/system` you can create the .fog config
-file with
+file with:
 
-    cat > ~/.fog << EOF
+    $ cat > ~/.fog << EOF
     :default:
       :libvirt_uri: qemu+ssh://cloud@myhost.com/system
+    EOF
 
-## Using VeeWee
-
-List available templates
-
-    veewee kvm templates
+For more information have a look at the
+[libvirt documentation](http://libvirt.org/drvqemu.html#uris).
 
-Use one of the listed templates to define a new box e.g. with
+## Using `veewee kvm` Subcommand
 
-    veewee kvm define 'My Ubuntu 12.10 box' 'ubuntu-12.10-server-amd64'
+You can always get help by using the the built-in help with every command:
 
-Build the box using KVM / Quemu (this will take a while)
+    $ bundle exec veewee kvm help build
 
-    veewee kvm build 'My Ubuntu 12.10 box'
+List available templates:
 
-You may want to use the VNC console (e.g. through virt-manager) to monitor /
-check the build process.
+    $ bundle exec veewee kvm templates
 
-## Options
+Use one of the listed templates to define a new box e.g. with:
 
-There is currently few options supported :
+    $ bundle exec veewee kvm define 'My Ubuntu 12.10 box' 'ubuntu-12.10-server-amd64'
 
-1. **network_type**: the type of network used by this box on libvirt. It could
-   be either _network_ (for using the default network) or _bridge_.
-2. **network_bridge_name**: the name of the bridge. It is used just in case
-   **network_type** is set to _bridge_.
-3. **pool_name**: the _storage_ pool name to be used when creating the box. If
-   not specified, the default one is used.
+Build the box using KVM / Quemu (this will take a while) with:
 
-## Notes
+    $ bundle exec veewee kvm build 'My Ubuntu 12.10 box'
 
-Remove modules:
+You can specify the name of the storage pool and the network to be used when
+building a VM. Use the options`--pool-name` and `--network-name` with the built
+command:
 
-    rmmod kvm_intel
-    rmmod kvm
+    $ bundle exec veewee kvm build 'My Ubuntu 12.10 box' --pool-name virtimages --network-name default