ievms-ruby 0.0.3 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: d1b1ed064b1f9f0d07deb7d8a1599131c33cfd1c
-  data.tar.gz: 89adcd248ac8f761c206df6e11c5eb6a7616c7da
+  metadata.gz: 249e1aad51f82e11e427dd5fae50c58761401f70
+  data.tar.gz: fd970f847bd82ad62e78525fccbf3689affd5db2
 SHA512:
-  metadata.gz: 71ad9eb8e5775cb37307cde8aa88ae8e9c7a850d63bb69f716db50cce3b6b726d448c19367ae439d54b89a02a5449bf228b5cd89f58b0d198ccb2c58fa2c8028
-  data.tar.gz: 1c498afdbe7b088c7c6d06ca7fc0b35a64b59b76df4363e3fe4985bf6b6e2b253b2dbf11238fa7eb3ef06c4350ccc390c7c067f8d494cf74f45392887b684276
+  metadata.gz: 036bd7897575e55f3f2a06a091a6c233c34fab0e111f536bf120dba21ba593b26d650776033c58ea4bc5a9ced55947fd2cb95eb16e53105c145a754b440f817b
+  data.tar.gz: b5d2a964d5a50c23e90cad5cdd53f14045352bcd22d13edf0a861fe07fe1c84eceed5a17027e9b04d7f4b3a28509fca1357259f5b946b781be1b981a28a84682

data/.gitignore

@@ -1,4 +1,5 @@
 /.bundle/
+/site
 /.yardoc
 /Gemfile.lock
 /_yardoc/
@@ -12,3 +13,4 @@
 *.o
 *.a
 mkmf.log
+/vendor/

data/README.md

@@ -21,66 +21,29 @@ Next to [ievms.sh](https://github.com/xdissent/ievms), `ievms-ruby` also works g
 
 ## Features
 
-* Upload files to guest machine
-* Download file from guest machine
+* Upload and download files from guest machine
 * Execute cmd.exe and powershell commands on guest machine
 * Execute cmd.exe and powershell commands on guest machine as admin
-* Cat file guest machine from cli
+* Shortcut commands for Windows guest like `cat`, `ps`, `reboot` and `shutdown`
+* To be used as CLI utility or as library in a ruby script.
 
 ## Requirements
 
+* Host Machine: OSX or Linux (only tested on OSX 10.9 & 10.10)
 * [VirtualBox](https://www.virtualbox.org/wiki/Downloads) >= 5.0.6
 * VirtualBox Extension Pack and Guest Additions >= 5.0.6
-* Host Machine: OSX or Linux (only tested on OSX 10.9 & 10.10)
-* Virtual Machines created by .ievms (only tested with vanilla Win7 machines)
+* Windows Machines created by [ievms](https://github.com/xdissent/ievms)
+
+### Recommended
+* [iectrl](https://github.com/xdissent/iectrl), cli interface for simple
+ ievms admin commands
 
 ## Usage
 
 ### As library
-Use Ievms-ruby in provisioning scripts for windows E.g. for CI. Here's an example
-provisioning script using the Gem. It installs [Chocolatey](https://chocolatey.org), Ruby, and [git-for-windows](https://git-for-windows.github.io) without user interaction needed.
-
-Add this line to your application's Gemfile:
-
-```ruby
-gem 'ievms-ruby'
-```
-
-run `bundle install`
-
-```ruby
-#!/usr/bin/env ruby
-require 'rubygems'
-require 'bundler/setup'
-require 'ievms/windows_guest'
-
-class ProvisionIE
-
-  # Create interface for the 'IE9 - Win7' virtual box
-  def init
-    @machine = Ievms::WindowsGuest.new 'IE9 - Win7'
-  end
-
-  # Install the choco package manager (APT for Windows)
-  def install_chocolatey
-    print "Installing Chocolatey\n"
-    choco_install_cmd = '@powershell -NoProfile -ExecutionPolicy unrestricted -Command "iex ((new-object net.webclient).DownloadString(\'https://chocolatey.org/install.ps1\'))" && SET PATH=%PATH%;%ALLUSERSPROFILE%\chocolatey\bin '
-    @machine.run_command_as_admin(choco_install_cmd)
-  end
-
-  # Install ruby and git stuff, the reason why we wrote ievms-ruby
-  def install_ruby_and_git
-    %w( ruby msysgit ).each do |pkg|
-      @machine.run_command_as_admin "c:\\ProgramData\\chocolatey\\bin\\choco install -y #{pkg}"
-    end
-  end
-end
-
-provision = ProvisionIE.new
-provision.init
-provision.install_chocolatey
-provision.install_ruby_and_git
-```
+Use Ievms-ruby in provisioning scripts for windows E.g. for Gitlab CI
+or Jenkins integration. There are provisioning example's located in the
+[ievms-ruby library documentation](http://mipmip.github.io/ievms-ruby/library/).
 
 ### From CLI
 Install the Gem on your system:
@@ -89,58 +52,53 @@ Install the Gem on your system:
 
 After installation you can use the `ievmsrb` cli program.
 
-#### ievmsrb commands
+Here's the output of `ievmsrb help`
 
 ```bash
 $ ievmsrb help
 
 Commands:
-  ievmsrb cat [vbox name] [file path]                        # cat file from path in Win vbox
-  ievmsrb cmd [vbox name] [command to execute]               # Run command with cmd.exe in Win vbox
-  ievmsrb copy_from [vbox name] [path in vbox] [local file]  # Copy file from Win vbox to local path
-  ievmsrb copy_to [vbox name] [local file] [path in vbox]    # Copy local file to Win vbox
-  ievmsrb help [COMMAND]                                     # Describe available commands or one specific command
-  ievmsrb ps [vbox name]                                     # Show running tasks in Win vbox
-  ievmsrb reboot [vbox name]                                 # Reboot Win box
-  ievmsrb shutdown [vbox name]                               # Shutdown Win vbox
+  ievmsrb cat [vbox name] [file path]                             # cat file from path in Win vbox
+  ievmsrb cmd [vbox name] [command to execute]                    # Run command with cmd.exe in Win vbox
+  ievmsrb cmd_adm [vbox name] [command to execute]                # Run command as Administrator with cmd.exe in Win vbox
+  ievmsrb copy_from [vbox name] [path in vbox] [local file]       # Copy file from Win vbox to local path
+  ievmsrb copy_to [vbox name] [local file] [path in vbox]         # Copy local file to Win vbox
+  ievmsrb copy_to_as_adm [vbox name] [local file] [path in vbox]  # Copy local file to Win vbox as Administrator
+  ievmsrb help [COMMAND]                                          # Describe available commands or one specific command
+  ievmsrb ps [vbox name]                                          # Show running tasks in Win vbox
+  ievmsrb reboot [vbox name]                                      # Reboot Win box
+  ievmsrb shutdown [vbox name]                                    # Shutdown Win vbox
 ```
 
-#### ievmsrb examples
+Read the docs for more info about [ievms-ruby CLI usage](http://mipmip.github.io/ievms-ruby/cli/).
 
-Display the contents of a guest file.
-```bash
-$ ievmsrb cat "IE9 - Win7" 'C:\Windows\System32\Drivers\Etc\hosts'
-```
+## Contributing
+Please submit a new ticket if you want to report an issue.
+Merge requests are welcome. See issues with `Help  Wanted` label.
 
+### Testing
+To run the tests you need to fullfil the testing requirements first:
 
-Execute a cmd on the guestmachine and show the output
-```bash
-$ ievmsrb cmd "IE9 - Win7" 'tasklist'
-```
+* Install VirtualBox >= 5.0.4 at time of writing 5.0.6
 
+* "IE9 - Win7" installed by ievms.sh and make sure its running
 
-Copy a file from the Windows Guest to a local path
-```bash
-$ ievmsrb copy_from "IE9 - Win7" 'C:\Windows\System32\Drivers\Etc\hosts' ~/Desktop/hosts.win9
-```
+* [iectrl](https://github.com/xdissent/iectrl), cli interface for simple
 
-Turn of the Filewall executing a command as Administator
 ```bash
-$ ievmsrb cmd_adm "IE9 - Win7" 'NetSh Advfirewall set allprofiles state off'
+$ npm install iectrl
+$ echo 'PATH="$HOME/node_modules/.bin:$PATH"' >> ~/.profile
+$ source ~/.Provider
 ```
 
-## Contributing
-Please submit a new ticket if you want to report an issue.
-Merge requests are welcome. See issues with `Help  Wanted` label.
-
-### Testing
-To run the tests you need top fullfil the testing requirements first:
-
-* VirtualBox >= 5.0.4
-* "IE9 - Win7" installed by ievms.sh
 * Create an new virtual machine called `standbymachine`. Keep the disk size as
   small as possible. It should be turned off.
 
+```bash
+VBoxManage createvm --name standbymachine --register
+```
+
+* clone ievms-ruby
 ```
 git clone https://github.com/mipmip/ievms-ruby.git
 cd ievms-ruby
@@ -164,5 +122,3 @@ bundle exec rake
 - modern.IE - Provider of IE VM images.
 - virtualbox - Software for running Virtual Machines
 - shields.io - Creates the beautiful Windows Badges
-
-

data/docs/cli.md

@@ -0,0 +1,56 @@
+# CLI util ievmsrb
+
+The gem ievms-ruby comes with a CLI program calles ievmsrb. This
+utility makes controlling virtual windows machines more easily is they
+are setup with ievms.
+
+## Installing ievmsrb
+Install the Gem on your system:
+
+    $ gem install ievms-ruby
+
+After installation you can use the `ievmsrb` cli program.
+
+## Usage
+Here's the output of `ievmsrb help`
+
+```bash
+$ ievmsrb help
+
+Commands:
+  ievmsrb cat [vbox name] [file path]                             # cat file from path in Win vbox
+  ievmsrb cmd [vbox name] [command to execute]                    # Run command with cmd.exe in Win vbox
+  ievmsrb cmd_adm [vbox name] [command to execute]                # Run command as Administrator with cmd.exe in Win vbox
+  ievmsrb copy_from [vbox name] [path in vbox] [local file]       # Copy file from Win vbox to local path
+  ievmsrb copy_to [vbox name] [local file] [path in vbox]         # Copy local file to Win vbox
+  ievmsrb copy_to_as_adm [vbox name] [local file] [path in vbox]  # Copy local file to Win vbox as Administrator
+  ievmsrb help [COMMAND]                                          # Describe available commands or one specific command
+  ievmsrb ps [vbox name]                                          # Show running tasks in Win vbox
+  ievmsrb reboot [vbox name]                                      # Reboot Win box
+  ievmsrb shutdown [vbox name]                                    # Shutdown Win vbox
+```
+
+## Some ievmsrb examples
+
+Display the contents of a guest file.
+```bash
+$ ievmsrb cat "IE9 - Win7" 'C:\Windows\System32\Drivers\Etc\hosts'
+```
+
+
+Execute a cmd on the guestmachine and show the output
+```bash
+$ ievmsrb cmd "IE9 - Win7" 'tasklist'
+```
+
+
+Copy a file from the Windows Guest to a local path
+```bash
+$ ievmsrb copy_from "IE9 - Win7" 'C:\Windows\System32\Drivers\Etc\hosts' ~/Desktop/hosts.win9
+```
+
+Turn of the Filewall executing a command as Administator
+```bash
+$ ievmsrb cmd_adm "IE9 - Win7" 'NetSh Advfirewall set allprofiles state off'
+```
+

data/docs/index.md

@@ -0,0 +1,15 @@
+# Welcome to ievms-ruby
+
+Ievms-ruby is a Ruby interface for Windows boxes made by
+[ievms.sh](https://github.com/xdissent/ievms). It helps you to provision
+your IE boxes from [modern.ie](https://modern.ie), but also great to use
+as CLI program to fire commands to a Windows machine without leaving
+your terminal.
+
+Here you can find all ievms-ruby documentation along with example scripts.
+
+If you'd like to fork ievms-ruby, see
+[http://github.com/mipmip/ievms-ruby](http://github.com/mipmip/ievms-ruby)
+
+
+![image](http://picdrop.t3lab.com/8I3tMPLniI.png)

data/docs/library.md

@@ -0,0 +1,29 @@
+# Ievms-ruby Library
+
+Use ievms-ruby as library to create provisioning scripts for ievms
+windows boxes. To examplain how to use ievms-ruby we have created some
+example scripts. But first you need to know how to use ievms-ruby in
+your project.
+
+## Install ievms-ruby gem
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'ievms-ruby'
+```
+
+run `bundle install` or `bunde install --path vendor`. If you're
+creating a standalone executable put these lines at on top of your script:
+
+```ruby
+#!/usr/bin/env ruby
+
+require 'rubygems'
+require 'bundler/setup'
+require 'ievms/windows_guest'
+```
+
+Now you can use the ievms-ruby API. Have a look at the
+[provisioning examples](provisioning_examples/) how.
+

data/docs/provisioning_examples.md

@@ -0,0 +1,43 @@
+# Provisioning examples
+
+Here you can find usable example provisioning scripts.
+
+## Auto install Chocolatey and git-for-windows
+
+provisioning script using the Gem. It installs [Chocolatey](https://chocolatey.org), Ruby, and [git-for-windows](https://git-for-windows.github.io) without user interaction needed.
+
+
+```ruby
+#!/usr/bin/env ruby
+require 'rubygems'
+require 'bundler/setup'
+require 'ievms/windows_guest'
+
+class ProvisionIE
+
+  # Create interface for the 'IE9 - Win7' virtual box
+  def init
+    @machine = Ievms::WindowsGuest.new 'IE9 - Win7'
+  end
+
+  # Install the choco package manager (APT for Windows)
+  def install_chocolatey
+    print "Installing Chocolatey\n"
+    choco_install_cmd = '@powershell -NoProfile -ExecutionPolicy unrestricted -Command "iex ((new-object net.webclient).DownloadString(\'https://chocolatey.org/install.ps1\'))" && SET PATH=%PATH%;%ALLUSERSPROFILE%\chocolatey\bin '
+    @machine.run_command_as_admin(choco_install_cmd)
+  end
+
+  # Install ruby and git stuff, the reason why we wrote ievms-ruby
+  def install_ruby_and_git
+    %w( ruby msysgit ).each do |pkg|
+      @machine.run_command_as_admin "c:\\ProgramData\\chocolatey\\bin\\choco "\
+        "install -y #{pkg}"
+    end
+  end
+end
+
+provision = ProvisionIE.new
+provision.init
+provision.install_chocolatey
+provision.install_ruby_and_git
+```

data/lib/ievms/ievms_cli.rb

@@ -1,4 +1,6 @@
 class IevmsRb < Thor
+  class_option :verbose, :desc => 'Be more verbose', :type => :boolean, :aliases => '-v'
+  class_option :timeout, :desc => 'Timeout in seconds', :type => :numeric
 
   desc "cat [vbox name] [file path]", "cat file from path in Win vbox"
   def cat(vbox_name,guest_path)
@@ -61,6 +63,9 @@ class IevmsRb < Thor
 
   def init vbox_name
     @machine = Ievms::WindowsGuest.new vbox_name
+    #@machine.methods.sort
+    @machine.verbose = true if options[:verbose]
+    @machine.timeout_secs = options[:timeout] if options[:timeout]
   end
 end
 

data/lib/ievms/version.rb

@@ -1,3 +1,3 @@
 module Ievms
-  VERSION = "0.0.3"
+  VERSION = "0.1.0"
 end

data/lib/ievms/windows_guest.rb

@@ -2,6 +2,7 @@ require "ievms/version"
 require 'open3'
 require 'fileutils'
 require 'tempfile'
+require 'timeout'
 
 # VM admin username
 USERNAME = 'IEUser'
@@ -15,10 +16,13 @@ IEVMS_HOME = ENV['HOME']+'/.ievms'
 module Ievms
   class WindowsGuest
     attr_accessor :verbose
-
-    @verbose = false
+    attr_accessor :timeout_secs
 
     def initialize(vbox_name)
+
+      @verbose = false
+      @timeout_secs = 600 #default timeout for a single task 5 minutes
+
       @vbox_name = vbox_name
 
       is_vm vbox_name
@@ -90,16 +94,19 @@ module Ievms
 
       upload_string_as_file_to_guest(command, 'C:\Users\IEUser\ievms.bat', true)
 
-      guestcontrol_exec "schtasks.exe", "schtasks.exe /run /tn ievms"
+      _ = Timeout::timeout(@timeout_secs) {
 
-      unless quiet
-        print "..."
-        while schtasks_query_ievms.include? 'Running'
-          print "."
-          sleep 2
+        guestcontrol_exec "schtasks.exe", "schtasks.exe /run /tn ievms"
+
+        unless quiet
+          print "..."
+          while schtasks_query_ievms.include? 'Running'
+            print "."
+            sleep 1
+          end
+          print "\n"
         end
-        print "\n"
-      end
+      }
 
     end
 
@@ -124,10 +131,16 @@ module Ievms
     # execute final guest control shell cmd
     # returns [stdout,stderr,status] from capture3
     def guestcontrol_exec(image, cmd)
-      wait_for_guestcontrol(@vbox_name)
-      cmd = "VBoxManage guestcontrol \"#{@vbox_name}\" run --username \"#{USERNAME}\" --password '#{PASSWD}' --exe \"#{image}\" -- #{cmd}"
-    #  print cmd + "\n"
-      return Open3.capture3(cmd)
+
+      _ = Timeout::timeout(@timeout_secs) {
+        wait_for_guestcontrol(@vbox_name)
+        cmd = "VBoxManage guestcontrol \"#{@vbox_name}\" run --username \"#{USERNAME}\" --password '#{PASSWD}' --exe \"#{image}\" -- #{cmd}"
+
+        log_stdout cmd, false if @verbose
+
+        return Open3.capture3(cmd)
+      }
+
     end
 
     # function taken from ievms

data/mkdocs.yml

@@ -0,0 +1,21 @@
+site_name: 'Ievms-ruby'
+pages:
+- [index.md, Home]
+- [cli.md, ievmsrb (CLI)]
+- [library.md, Ievms-ruby library]
+- [provisioning_examples.md, Provisioning Examples]
+theme: readthedocs
+#theme: cerulean
+#theme: amelia
+#theme: bootstrap
+#theme: cosmo
+#theme: cyborg
+#theme: flatly
+#theme: journal
+#theme: mkdocs
+#theme: readable
+#theme: simplex
+#theme: slate
+#theme: spacelab
+#theme: united
+#theme: yeti

data/test/test_helper.rb

@@ -1,6 +1,5 @@
 require 'simplecov'
 
-
 SimpleCov.start do
   add_filter '/test/'
   add_filter '/vendor/'
@@ -13,3 +12,29 @@ require 'minitest/pride'
 
 require "codeclimate-test-reporter"
 CodeClimate::TestReporter.start
+
+module IevmsRubyTestsShared
+
+  def initialize(name = nil)
+    print "Running test case: #{name}\n"
+    @test_name = name
+    super(name) unless name.nil?
+  end
+
+  def ensure_machine_running vbox_name
+
+    iectrl = `iectrl status "#{vbox_name}"`
+    if not iectrl.include?('RUNNING')
+      iectrl = `iectrl start "#{vbox_name}"`
+      sleep 5
+      iectrl = `iectrl status "#{vbox_name}"`
+      if not iectrl.include?('RUNNING')
+        iectrl = `VBoxManage startvm --type headless "#{vbox_name}"`
+        sleep 5
+      end
+
+      IevmsRb.start(['ps', "IE9 - Win7"])
+    end
+
+  end
+end

data/test/test_ievms_cli.rb

@@ -5,16 +5,17 @@ require 'ievms/windows_guest'
 require 'timeout'
 
 class TestWin7 < Minitest::Test
+  include IevmsRubyTestsShared
+
+
   def setup
-    iectrl = `iectrl status "IE9 - Win7"`
-    if not iectrl.include?('RUNNING')
-      iectrl = `iectrl start "IE9 - Win7"`
-      sleep 5
-      IevmsRb.start(['ps', "IE9 - Win7"])
-    end
+    ensure_machine_running("IE9 - Win7")
   end
 
-  def test_non_existing_guest
+  def test_timeout_option
+    assert_raises {
+      run_capture(["cmd", "IE9 - Win7", "ping 127.0.0.1 -n 6 > nul", "--verbose", "--timeout", "3" ])
+    }
   end
 
   def test_ps
@@ -42,7 +43,6 @@ class TestWin7 < Minitest::Test
     out2 = run_capture ['cat',"IE9 - Win7", 'C:\Users\IEUser\ievms_test_upload3.txt']
     assert_equal "[IE9 - Win7] Copying /tmp/ievms_test_upload3.txt to C:\\Users\\IEUser\\ievms_test_upload3.txt\n", out
     assert_match(/uploadasadmin_yes/, out2)
-
   end
 
   def test_copy_to_as_adm
@@ -54,7 +54,6 @@ class TestWin7 < Minitest::Test
     out2 = run_capture ['cat',"IE9 - Win7", 'C:\ievms_test_upload2.txt']
     assert_equal "[IE9 - Win7] Copying /tmp/ievms_test_upload2.txt to C:\\ievms_test_upload2.txt as Administrator\n", out
     assert_match(/uploadasadmin_yes/, out2)
-
   end
 
   def test_reboot

data/test/test_ievms_win7.rb

@@ -3,15 +3,11 @@ require 'ievms/windows_guest'
 require 'timeout'
 
 class TestWin7 < Minitest::Test
-  def setup
 
-    iectrl = `iectrl status "IE9 - Win7"`
-    if not iectrl.include?('RUNNING')
-      iectrl = `iectrl start "IE9 - Win7"`
-      sleep 5
-      IevmsRb.start(['ps', "IE9 - Win7"])
-    end
+include IevmsRubyTestsShared
 
+  def setup
+    ensure_machine_running("IE9 - Win7")
     @machine = Ievms::WindowsGuest.new 'IE9 - Win7'
   end
 
@@ -33,10 +29,28 @@ class TestWin7 < Minitest::Test
 
   end
 
+  def test_long_cmd
+    @machine.run_command 'ping 127.0.0.1 -n 6 > nul'
+  end
+
   def test_long_admin_cmd
     @machine.run_command_as_admin 'ping 127.0.0.1 -n 6 > nul'
   end
 
+  def test_long_cmd_timeout
+    @machine.timeout_secs = 3
+    assert_raises {
+      @machine.run_command 'ping 127.0.0.1 -n 6 > nul'
+    }
+  end
+
+  def test_long_admin_cmd_timeout
+    @machine.timeout_secs = 3
+    assert_raises {
+      @machine.run_command_as_admin 'ping 127.0.0.1 -n 6 > nul'
+    }
+  end
+
   def test_upload_string_as_file
     @machine.run_command 'if exist C:\Users\IEUser\testfile.txt del C:\Users\IEUser\testfile.txt && Exit'
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ievms-ruby
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.1.0
 platform: ruby
 authors:
 - Pim Snel
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-10-12 00:00:00.000000000 Z
+date: 2015-10-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -94,10 +94,15 @@ files:
 - README.md
 - Rakefile
 - bin/ievmsrb
+- docs/cli.md
+- docs/index.md
+- docs/library.md
+- docs/provisioning_examples.md
 - ievms-ruby.gemspec
 - lib/ievms/ievms_cli.rb
 - lib/ievms/version.rb
 - lib/ievms/windows_guest.rb
+- mkdocs.yml
 - test/_test.bat
 - test/_test_as_admin.bat
 - test/test_helper.rb