VIRTMACHINES

This is documentation for ASP developers about how set up a Linux
virtual machine and build ASP and its dependencies inside of it. A
virtual machine makes it easier work on a desired OS version and to
install third-party libraries.

We use KVM to manage virtual machines. The system administrators
need to have it installed on the host machine. 

It is suggested that the virtual machine (the guest) to be used for
building ASP be reasonably old, so that the shipped ASP build works on
as many machines as possible. Here is an example of installing CentOS 7
as a guest.

wget http://archive.kernel.org/centos-vault/7.0.1406/isos/x86_64/CentOS-7.0-1406-x86_64-livecd.iso
mkdir -p ~/projects/libvrt
fallocate -l 100000M ~/projects/libvrt/centos7.img
virt-install -r 12288 --accelerate -n centos7 -f ~/projects/libvrt/centos7.img --cdrom CentOS-7.0-1406-x86_64-livecd.iso --vcpus=14 --vnc --vncport=5950

One should choose to use manual partitioning and create a single drive
rather than having the space divided among multiple logical drives
which makes it harder to use the space efficiently.

# Managing the virtual machine

To open a GUI in the machine, use either:

  vncviewer localhost:5950

(the same VNC port used when the machine was created), or 

  virt-viewer centos7

Use

  virsh list --all 

to view the guests, 

  virsh start <machine> 

to start it, 

  virsh destroy <machine> 

to force shutting down the guest, and 

  virsh undefine <guest> 

followed by 

  rm -rf ~/projects/libvrt 

to wipe any trace of all guest machines (use with extreme care!).

# Connecting to the guest via ssh using remote port forwarding

A connection from the host to a guest can be done by reverse port 
forwarding (there should be a better way). 

Here is an example. From the guest, one can do:

ssh -f -N HOSTUSER@HOST -R 6000:localhost:22

Then, from HOST, one should be able to connect to the guest via:

  ssh localhost -p 6000 -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no -l GUESTUSER

The guest must be configured to allow incoming ssh connections by
installing openssh-server. The sshd daemon may need to be installed or
restarted on the guest, using:

sudo service sshd restart

If the following lines are added to HOST's .ssh/config:

Host GUEST
  Hostname localhost
  HostKeyAlias GUEST
  CheckHostIP no
  Port 6000
  User GUESTUSER

then one should be able to connect to the guest simply by running 
ssh GUEST. 

Occasionally a port may become unavailable, and hence will need to be changed.

# Speeding up network access

The network speed between HOST and GUEST can be very slow. It can be
greatly sped up using virtio. This can be done as follows.

Locate the virtual machine, for example, with the command:

virsh list --all

on the host. Here it is assumed we name it centos7.

Dump and edit an xml file:

virsh dumpxml centos7 > centos7.xml
vim centos7.xml

Under the line

 <mac address='...'/> 

add the line:

 <model type='virtio'/>   

Save this file and exit. Then undefine, shut down, redefine, and
restart the machine as follows:

virsh undefine centos7
virsh destroy centos7
virsh create centos7.xml

This should create and start the machine. 

# Further customization and administration

The number of CPUs and RAM for GUEST can be changed each time before
starting it by again editing the xml file.

See INSTALLGUIDE for how to continue the installation of dependencies
and building ASP.

To bring up the network connection on CentOS, run:

  dhclient eth0

One should also change the machine name of the guest to, for example,
centos7 and reflect this in the daily regression scripts in
BinaryBuilder.