README

   1 Automated VM Builder
   2 ====================
   3 :toc:
   4 :numbered:
   5
   6 This automated VM Builder script set is intended to allow someone who does not
   7 have experience setting up Evergreen get one or more "test" virtual machines
   8 running. The initial setup should be done by someone familiar with linux, or
   9 more specifically Ubuntu, after which setting up new test virtual machines is
  10 hopefully as simple as running a command and waiting for things to finish.
  11
  12 Host Machine Requirements
  13 -------------------------
  14
  15 This script setup currently expects to be running on an Ubuntu system and uses
  16 the ubuntu-vm-builder package. In addition, the host machine will need to
  17 support hardware virtualization.
  18
  19 The latter can be checked by running kvm-ok, which is provided by cpu-checker.
  20
  21 [source,bash]
  22 --------------------------------------------------------------------------------
  23 sudo apt-get install cpu-checker
  24 kvm-ok
  25 --------------------------------------------------------------------------------
  26
  27 Depending on your system configuration you may need to change bios settings to
  28 enable hardware virtualization before kvm-ok will return success.
  29
  30 Required Packages
  31 ~~~~~~~~~~~~~~~~~
  32
  33 In order to build virtual machines you will need several packages. The command
  34 below should install the packages you need.
  35
  36 [source,bash]
  37 --------------------------------------------------------------------------------
  38 sudo apt-get install ubuntu-vm-builder kvm libvirt-bin git wget
  39 --------------------------------------------------------------------------------
  40
  41 After installing those packages you should add the user you wish to run the
  42 scripts as to the libvirtd group as well, giving them the ability to control
  43 virtual machines. This is accomplished with the following command.
  44
  45 [source,bash]
  46 --------------------------------------------------------------------------------
  47 sudo adduser $USER libvirtd
  48 --------------------------------------------------------------------------------
  49
  50 Bridge Configuration
  51 ~~~~~~~~~~~~~~~~~~~~
  52
  53 In order to get the virtual machine(s) onto the network you will need to setup
  54 at least one bridge. To set one up manually you should edit the
  55 /etc/network/interfaces file.
  56
  57 It is recommended that when using bridges you disable the original interface(s)
  58 by commenting out the "auto eth#" line(s). You would then add a new bridge that
  59 is configured similarly to the original interface:
  60
  61 [source]
  62 --------------------------------------------------------------------------------
  63 # Static Configuration
  64 iface br0 inet static
  65         address 10.0.0.2
  66         netmask 255.255.255.0
  67         network 10.0.0.0
  68         broadcast 10.0.0.255
  69         gateway 10.0.0.1
  70         dns-nameservers 10.0.0.1 10.0.0.254
  71         dns-search example.com
  72         bridge_ports eth0
  73         bridge_fd 9
  74         bridge_hello 2
  75         bridge_maxage 12
  76         bridge_stp off
  77
  78 # DHCP configuration
  79 iface br1 inet dhcp
  80         bridge_ports eth1
  81         bridge_fd 9
  82         bridge_hello 2
  83         bridge_maxage 12
  84         bridge_stp off
  85 --------------------------------------------------------------------------------
  86
  87 I recommend naming your bridge interfaces similarly to the network interface you
  88 are using for the bridge. That is, eth# becomes br# so that:
  89     * eth0 = br0
  90     * eth1 = br1
  91     * eth4 = br4
  92
  93 If you are configured to support multiple VLANs on your interfaces then follow
  94 the overall pattern:
  95     * eth0.5 = br0.5
  96     * eth1.120 = br1.120
  97     * eth4.30 = br4.30
  98
  99 This overall bridge naming scheme helps to ensure you know exactly where your
 100 virtual machines are being attached to the network.
 101
 102 Optional: Local caching
 103 ~~~~~~~~~~~~~~~~~~~~~~~
 104
 105 Locally caching install packages may be of benefit for repeated VM building. The
 106 two areas that benefit from this the most are apt and CPAN.
 107
 108 For CPAN I find a local mirror works well and how/where/if you set one up is up
 109 to you. Instructions can be obtained from CPAN here:
 110 http://www.cpan.org/misc/how-to-mirror.html
 111
 112 For apt I find that apt-cacher or variants thereof work well and don't require
 113 the storage space of a full apt mirror.
 114
 115 Configuration
 116 -------------
 117
 118 Base config
 119 ~~~~~~~~~~~
 120
 121 For the base configuration you should copy "config.example" to "config" and then
 122 make your changes, if any. Reasonable defaults have been provided for all
 123 options though you may want to pay attention to the following.
 124
 125 Repo Locations
 126 ++++++++++++++
 127
 128 The GIT Repo locations can be configured to allow for local or alternate mirrors
 129 to be used instead of the official ones. Note that in most cases only the
 130 working repos are actually loaded.
 131
 132 EGVMUSEDOMAIN
 133 +++++++++++++
 134
 135 If your vmname.domain values resolve then it is recommended that you turn this
 136 setting on. By doing so the staff clients built will use the domain for the
 137 initial hostname and automatic updates.
 138
 139 EGVMSMARTHOST
 140 +++++++++++++
 141
 142 If you wish to test email delivery you will want to set this to an appropriate
 143 mail server. With it set all email generated by the server will be delivered to
 144 the server in question. Information on capturing all mail from a given host when
 145 using postfix is provided in a later section.
 146
 147 Without this option no mail delivery will be supported.
 148
 149 EGVMAPTMIRROR and EGVMCPANURLLIST
 150 +++++++++++++++++++++++++++++++++
 151
 152 These options control whether or not local mirrors or cache servers are used for
 153 apt and CPAN. EGVMAPTMIRROR can also be used to point at an apt cacher or proxy.
 154
 155 Individual VM configuration
 156 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 157
 158 In the vmbuilder folder you should find an example configuration file. Using
 159 that file as a base you will need to create one or more hostname.conf files.
 160
 161 Each hostname.conf file defines a different virtual machine that can be built.
 162 You will specify the network information, password, memory, cpu count, drive and
 163 swap sizes, and suite information here at a minimum.
 164
 165 SSL Certificates
 166 ~~~~~~~~~~~~~~~~
 167
 168 In addition to everything else you will need to provide SSL certificates. For
 169 ease of testing I recommend using a single domain for all the virtual machines
 170 and obtaining a single wildcard certificate for the set.
 171
 172 The crt file, key file, and if needed chain (or bundle) file should be placed in
 173 the files/ssl folder to be automatically copied into place in the individual
 174 virtual machines. If a chain.crt file is present the virtual machines will
 175 automatically add the proper configuration lines to use it.
 176
 177 Building VMs
 178 ------------
 179
 180 Once everything is configured you will need to build the VMs. At this stage it
 181 may be beneficial to either ensure you do not need a password to run "sudo" or
 182 that you have pre-entered the password by running "sudo -v".
 183
 184 The command for setting up a virtual machine is setupvm and the only required
 185 argument is the virtual machine name. If vmbuilder/$VMNAME.conf does not exist
 186 then the script will report as such.
 187
 188 [source,bash]
 189 --------------------------------------------------------------------------------
 190 ./setupvm testsystem
 191 --------------------------------------------------------------------------------
 192
 193 You can also specify branches to load in the Evergreen, OpenSRF, and (if enabled
 194 in config) SIPServer repositories. These branches are generally expected to be
 195 located in the community "working" repositories. The syntax is project:branch.
 196
 197 [source,bash]
 198 --------------------------------------------------------------------------------
 199 ./setupvm testsystem Evergreen:working/user/somedude/lpsomething
 200 --------------------------------------------------------------------------------
 201
 202 You can specify as many branches as you want. Note, however, that if any of the
 203 branches do not merge cleanly and automatically then the virtual machine will
 204 fail to build.
 205
 206 In the event you wish to test a branch against something other than master you
 207 can specify that with repo:BASE:branch, which will check out the branch from the
 208 main git repository. This should be done *before* any merge branches are
 209 specified as the actions are taken in order.
 210
 211 [source,bash]
 212 --------------------------------------------------------------------------------
 213 ./setupvm testsystem Evergreen:BASE:rel_2_7 Evergreen:working/user/somedude/lpsomething_2_7
 214 --------------------------------------------------------------------------------
 215
 216 Capturing email with Postfix
 217 ----------------------------
 218
 219 It is possible to configure a postfix install to capture all mail from a given
 220 host, or set of hosts, into a given account. By doing this you can ensure that
 221 any email generated by a test system can be examined without worry about the
 222 apparent destination. This is generally a useful configuration for training,
 223 development, and test systems.
 224
 225 This script's side of this is configured with the EGVMSMARTHOST option in the
 226 config file. The specified smarthost, however, will need to be configured to
 227 capture email. This is easily done with a check_client_access configuration
 228 utilizing the REDIRECT parameter. For example, if you have /etc/postfix/access
 229 containing the following:
 230
 231 [source]
 232 --------------------------------------------------------------------------------
 233 10.0.0.10 REDIRECT testserver0@domain.ext
 234 10.0.0.11 REDIRECT testserver1@domain.ext
 235 --------------------------------------------------------------------------------
 236
 237 You will need to compile that into a hash file:
 238
 239 [source,bash]
 240 --------------------------------------------------------------------------------
 241 sudo postalias hash:/etc/postfix/access
 242 --------------------------------------------------------------------------------
 243
 244 And then you can add to, for example, smtpd_recipient_restrictions to check the
 245 newly created hash:
 246
 247 [source]
 248 --------------------------------------------------------------------------------
 249 check_client_access hash:/etc/postfix/access,
 250 --------------------------------------------------------------------------------