ievms-ruby

Gem Version Code Climate Test Coverage Dependency Status Inline docs

Ruby interface for managing and provisioning IE/Windows Machines from https://modern.ie.

WinBoxes supported

winxp winvista win7 win8 win10

Features

  • Upload and download files from guest machine
  • Execute cmd.exe and powershell commands on guest machine
  • Execute commands on guest machine as admin
  • CLI with shortcut commands for Windows guests like cat, ps, reboot and shutdown
  • Integrated Chocolatey commands to easily install packages

Requirements

  • Host Machine: OSX or Linux (only tested on OSX 10.9 & 10.10)
  • VirtualBox >= 5.0.6
  • VirtualBox Extension Pack and Guest Additions >= 5.0.6
  • Windows Machines created by ievms

Usage

As library

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.

From CLI

Install the Gem on your system:

$ gem install ievms-ruby

After installation you can use the ievmsrb cli program.

Here's the output of ievmsrb help

$ ievmsrb help

Commands:
  ievmsrb cat [vbox name] [file path]                             # cat file from path in Win vbox
  ievmsrb choco_inst [vbox name] [package]                        # Install package in win box with Chocolatey
  ievmsrb choco_uninst [vbox name] [package]                      # Uninstall package in win box with Chocolatey
  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 pwrsh_as_adm [vbox name] [command to execute]           # Run command as Administrator with PowerShell in Win vbox
  ievmsrb reboot [vbox name]                                      # Reboot Win box
  ievmsrb reset_ievms_taskmgr [vbox name]                         # Reset ievms task manager
  ievmsrb restore_clean [vbox name]                               # Restore clean snapshot
  ievmsrb shutdown [vbox name]                                    # Shutdown Win vbox
  ievmsrb start [vbox name]                                       # Start Win box
  ievmsrb version                                                 # display version

Options:
  -v, [--verbose], [--no-verbose]  # Be more verbose
      [--timeout=N]                # Timeout in seconds

Read the docs for more info about ievms-ruby CLI usage.

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:

  • Install VirtualBox >= 5.0.4 at time of writing 5.0.6

  • "IE9 - Win7" installed by ievms.sh and make sure its running

curl -s https://raw.githubusercontent.com/xdissent/ievms/master/ievms.sh | env IEVMS_VERSIONS="9" bash
  • Create an new virtual machine called standbymachine. Keep the disk size as small as possible. It should be turned off.
VBoxManage createvm --name standbymachine --register
  • clone ievms-ruby git clone https://github.com/mipmip/ievms-ruby.git cd ievms-ruby bundle install bundle exec rake

Merge Requests

  1. Fork it ( https://github.com/mipmip/ievms-ruby/fork )
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create a new Pull Request

Troubleshooting

  • If tests fail check if virtualbox guest additions 5.0.6 or higher are installed

Acknowledgements

  • ievms - Provider of a platform and methology
  • modern.IE - Provider of IE VM images.
  • virtualbox - Software for running Virtual Machines
  • shields.io - Creates the beautiful Windows Badges