tools/tools_vm/README.md

   1 ## Integration Team Tools VM
   2
   3 This Vagrantfile provides VMs with many of the tools used by the OpenDaylight Integration Team pre-installed and configured. It's meant to serve as a known-working, reproducible, clearly defined environment for consuming them.
   4
   5 ### Pre-installed Software
   6
   7 Note that the Vagrant environment is configure to support X forwarding, so GUI programs like RIDE will display correctly.
   8
   9 #### OpenDaylight
  10
  11 The latest OpenDaylight release is installed via the [OpenDaylight Puppet module](https://github.com/dfarrell07/puppet-opendaylight). Because we're using the Puppet mod, we get systemd config, user:group management, the correct Java package and any future maintenance/features for free.
  12
  13 #### Netopeer
  14
  15 [Netopeer](https://code.google.com/p/netopeer/) is an Open Source NETCONF server that can be used to explore the MD-SAL/RESTCONF.
  16
  17 #### Robot Famework
  18
  19 The [Robot Framework](http://robotframework.org/) is used by OpenDaylight to create system integration tests.
  20
  21 #### RIDE
  22
  23 [RIDE](https://github.com/robotframework/RIDE) is an editor for working with Robot Framework test cases.
  24
  25 To access the RIDE GUI:
  26
  27 ```ShellSession
  28 [vagrant@tools-fedora ~]$ ride
  29 ```
  30
  31 ### Dependencies
  32
  33 #### Installing Vagrant
  34
  35 If you don't have Vagrant installed, head over to the [Vagrant Downloads](https://www.vagrantup.com/downloads.html) page and grab the latest version for your OS. Fedora/RHEL/CentOS folks need the RPM package, Ubuntu/Debian folks need the DEB package. Note that Vagrant also supports Windows and OSX.
  36
  37 Assuming you're on Fedora/RHEL/CentOS, find the .rpm file you just downloaded and install it:
  38
  39 ```ShellSession
  40 sudo rpm -i <name of rpm>
  41 ```
  42
  43 Vagrant uses various "providers" for virtualization support. By default, it uses VirtualBox. If you don't have VirtualBox installed, you'll see an error message when you try to `vagrant up` anything. Install VirtualBox (Fedora/RHEL/CentOS):
  44
  45 ```ShellSession
  46 $ sudo yum install VirtualBox kmod-VirtualBox -y
  47 ```
  48
  49 You may need to restart your system, or at least `systemctl restart systemd-modules-load.service`. If you see Kernel-related errors, try that.
  50
  51 #### Installing Required Gems
  52
  53 We use Bundler to make gem management trivial.
  54
  55 ```ShellSession
  56 $ gem install bundler
  57 $ bundle install
  58 ```
  59
  60 Among other things, this will provide `librarian-puppet`, which is required for the next section.
  61
  62 #### Installing Required Puppet Modules
  63
  64 Once you've installed `librarian-puppet` through Bundler (as described above), you can use it to install our Puppet module dependences.
  65
  66 ```ShellSession
  67 $ librarian-puppet install
  68 $ ls modules
  69 archive  java  opendaylight  stdlib
  70 ```
  71
  72 ### Configuration
  73
  74 To configure the RAM and CPU resources to be used by the tools boxes, adjust the variables at the top of the Vagrantfile.
  75
  76 ```ruby
  77 # Set memory value (MB) and number of CPU cores here
  78 $MEMORY = "2048"
  79 $CPU = "2"
  80 ```
  81
  82 To configure the ODL install, adjust the params passed to the [OpenDaylight Puppet module](https://github.com/dfarrell07/puppet-opendaylight) in `manifests/odl_install.pp`.
  83
  84 By default, the newest ODL stable release will be installed via its RPM.
  85
  86 ### Common Vagrant commands
  87
  88 Since this Vagrantfile defines a multi-machine environment, it's mandatory to give the name of the box for most Vagrant command. For example, `vagrant up` should be `vagrant up <name of box>`.
  89
  90 #### Gathering information
  91
  92 Use `vagrant status` to see the supported boxes and their current status.
  93
  94 ```ShellSession
  95 $ vagrant status
  96 Current machine states:
  97
  98 fedora                    not created (virtualbox)
  99 ubuntu                    not created (virtualbox)
 100 ```
 101
 102 #### Starting boxes
 103
 104 To start a tools VM:
 105
 106 ```ShellSession
 107 $ vagrant up <name of box>
 108 ```
 109
 110 For example, to start the Fedora tools VM:
 111
 112 ```ShellSession
 113 $ vagrant up fedora
 114 ```
 115
 116 #### Connecting to boxes
 117
 118 To get a shell on a tools VM:
 119
 120 ```ShellSession
 121 $ vagrant ssh <name of box>
 122 ```
 123
 124 For example, to connect to the Fedora tools VM:
 125
 126 ```ShellSession
 127 $ vagrant ssh fedora
 128 [vagrant@tools-fedora ~]$
 129 ```
 130
 131 #### Cleaning up boxes
 132
 133 Suspending a tools VM will allow you to re-access it quickly.
 134
 135 ```ShellSession
 136 $ vagrant suspend <name of box>
 137 ```
 138
 139 To totally remove a VM:
 140
 141 ```ShellSession
 142 $ vagrant destroy -f <name of box>
 143 ```