Difference between revisions of "Howto build VyOS 1.2 ISO image and VMWare .OVF"

From VyOS Wiki
Jump to: navigation, search
m (Executive Summary)
m (Background: - Fix typo)
 
(20 intermediate revisions by 2 users not shown)
Line 1: Line 1:
Please Note This is a work in progress. Expect to be completed by 3 July 2017
+
=== Background ===
  
== Executive Summary ==
+
I have been interested in getting VyOS to run as a Google Cloud Compute instance for quite sometime. Unfortunately, the current version of VyOS 1.1.x is based upon Debian 6 which just does not work (unless you jump through many more hoops than I am willing to jump through), so I became curious to see if this would be possible with VyOS 1.2. As I began my investigation into what it would take to compile VyOS 1.2 I noticed that all the documentation was present, but it was not that easy to use (IMHO) and I discovered several "gotchas". The purpose of this HowTo is provide a complete set of instructions on how to compile VyOS 1.2 and point out some of the issues I encounter so that others can do what I did easier and faster.
  
This HowTo describes how to build VyOS 1.2 from source.  
+
This HowTo assumes you are familiar with installing Linux and are comfortable working in the Linux shell/command line.
  
I am a long time fan of VyOS. I was an early adopter of Vyatta. I have been stymied by the current VyOS 1.1.x builds specifically that it has been build on Debian 6, which has limited my ability to deploy it as widely as I would like. I started looking at VyOS 1.2. Building VyOS 1.2 has a lot of little "bits" and while these are documented in the various readme files I did not find the process as easy and streamlined as possible. so I created this document.
+
Enjoy.
  
This HowTo assumes you are familiar with installing Linux and are comfortable working in a command line.
+
--Max Abramowitz.
  
- [[max1e6]]
+
=== Building VyOS 1.2 ===
  
=== 20,000 Foot Overview ===
+
==== Create Build Machine ====
  
# Create VyOS build machine
+
The first step is to download and build a Debian 8 build machine. You can download Debian 8 "Jesse" from:
# Download and install prerequisite software
 
# Build ISO image
 
# Build qemu image
 
# Build vmware image
 
  
== Create and Basic Build Machine Setup ==
+
* (https://www.debian.org/releases/jessie/)
  
# Download Debian 8 "jesse" (https://www.debian.org/releases/jessie/)
+
: [[File:lookout.png]] Most of the build process can be done from the Linux shell. However, troubleshooting the qemu build process requires vncviewer which requires a graphical desktop environment. The screenshot below show the settings using in my testing.
# Install Debian either on a dedicated machine or as a virtual machines.
+
: [[File:VyOS1.2 screenshot1.png|500px|Left|VyOS build machine initial software configuration]]
  
Once the build machine is created install sudo, open-vm-tools (if running in a VMWare virtual machine, which is not strictly necessary and it makes life a bit easier) and your preferred text editor.
+
==== Preliminary Build Machine Configuration ====
'''Aside:''' There are two types of Unix heads in the world...those that use vi and those that use emacs. I am in the latter camp. To quote my college friend Steph Baily, "One should know vi well enough to compile and run emacs."
 
  
'''NOTE:''' ''The following commands should be run as root.''
+
Before installing software you will want to perform some basic configuration of your build machine. Install sudo, add your user account to the sudo group, install open-vm-tools (if your build machine is a VMware virtual machine and install your preferred text editor). Below are the configuration commands I used (these commands were run as root user):
  
  apt-get install sudo
+
  '''#''' apt-get install sudo
  apt-get install open-vm-tools
+
  '''#''' adduser <username> sudo
  apt-get install emacs
+
'''#''' apt-get install open-vm-tools
 +
  '''#''' apt-get install emacs
  
== Install Required Software ==
+
: [[File:lookout.png]] - For some reason the left mouse button does not work with Debian under VMware (at least out of the box). There are a couple of articles on the Internet about this. I was able to login and get a terminal window open using a combination of the keyboard and the right mouse button. Once open-vm-tools was installed the left mouse started working.
  
When I was going through the process of building VyOS 1.2 I discovered that there are a lot of little "bits" of software needed to compile and build the ISO, qemu and VMWare files. This is covered in the readme file associated with the VyOS 1.2 source, but many details were not so easy to follow, so I thought I would create this doc.
+
Installing sudo and adding your user account to the sudo group is not strictly necessary, but it allows you to do the build process from a non-root / non-privileged account, which is a security best practice.
  
 +
=== Installing Required Software Components ===
 +
 +
Install the basic software needed:
  
 
  sudo apt-get install git autoconf automake dpkg-dev syslinux genisoimage qemu jq libz-dev zip python3 live-build pbuilder devscripts python3-pystache
 
  sudo apt-get install git autoconf automake dpkg-dev syslinux genisoimage qemu jq libz-dev zip python3 live-build pbuilder devscripts python3-pystache
  
=== Download & Install Packer ===
+
There are a few components you will have to download from the Internet in order to build VyOS 1.2:
 +
 
 +
* HashiCorp Packer - tool to build automated machine images
 +
* VMWare open-vmdk
 +
* VMWare ovftool
 +
 
 +
==== Packer ====
 +
 
 +
Download Packer (http://www.packer.io/downloads.html). Upload to server. Unzip. Copy to a bin directory.
 +
 
 +
unzip packer_1.0.2_linux_amd64.zip
 +
sudo cp packer /usr/local/bin/
 +
 
 +
==== VMWare open-vmdk ====
 +
 +
git clone https://github.com/vmware/open-vmdk
 +
cd open-vmdk/
 +
make
 +
sudo make install
 +
 
 +
==== VMWare ovftool ====
 +
 
 +
You will need a VMWare account to download VMWare ovftool. Goto https://www.vmware.com/support/developer/ovf/. Click Software Download. Download the VMware OVF tool for Linux 64-bit. Upload the bundle to your build machine.
 +
 
 +
chmod 755 VMware-ovftool-4.2.0-4586971-lin.x86_64.bundle
 +
sudo ./VMware-ovftool-4.2.0-4586971-lin.x86_64.bundle
 +
 
 +
Follow the prompts to complete the installation
 +
 
 +
=== Building .ISO Image &amp; VMware .OVF Files ===
 +
 
 +
At this point all the software for building an ISO image should be installed on your build system and you can proceed with downloading the source code and building an ISO image
 +
 
 +
  git clone https://github.com/vyos/vyos-build.git
 +
  cd vyos-build
 +
  ./configure
 +
  sudo make iso
 +
 
 +
Go get a cup of coffee. Once the build process is complete the .iso file will be in the build folder
 +
 
 +
==== Building qemu image ====
 +
 
 +
At this point you have a working .iso image and we can proceed with building the qemu image. Before we build the qemu image you will need to create a private SSL key.
 +
 
 +
===== Create privatekey.pem =====
 +
 
 +
mkdir key
 +
openssl genrsa -des3 -out key/privatekey.pem 2048
 +
 
 +
===== Install VNC Viewer =====
 +
 
 +
As mentioned previously, you will need a VNC viewer client to monitor the qemu build process. I used the synaptic package manage to install Tight VNC Viwer.
 +
 
 +
===== packer.json =====
 +
 
 +
Part of the process of building a qemu image is to boot VyOS, install it in a qemu virtual machine and configure the vm to use DHCP, remove the hardware id for the interface and enable SSH. This is done with packer and a set of boot commands. The boot commands are set/configured in the packer.json file. The packer.json file is located in the scripts directory. The boot commands in the packer.json file relies on somewhat arbitrary timings. My initial experience was that the default timings in the packer.json file did not work with my build machine (the timings were not long enough and the qemu build process failed). I needed to modify the packer.json file and adjust the timings of the boot commands to work with my build environment.
 +
 
 +
Look at the packer.json file. There is a section labelled "boot_command": under that section are the key commands sent to the qemu vm during the install/configuration process. The documentation for the boot commands can be found at https://www.packer.io/docs/builders/qemu.html (scroll down to the bottom of the page).
 +
 
 +
The most relevant boot command for your purposes is the <wait> command:
 +
 
 +
;<wait>
 +
: wait 1 second.
 +
 
 +
;<wait5>
 +
: wait 5 seconds.
 +
 
 +
;<wait10>
 +
: wait 10 seconds.
 +
 
 +
;<waitXX>
 +
: wait some arbitrary time. Examples:
 +
: <wait15s> - wait 15 seconds.
 +
: <wait10m> - wait 10 minutes.
 +
: <wait1m30s> - wait 1 minute 30 seconds.
 +
 
 +
'''Note:''' - the default delay between keypresses is 100ms.
 +
 
 +
===== Actually building qemu image =====
 +
 
 +
Open vnc viewer on your build machine.
 +
 
 +
sudo make qemu
 +
 
 +
You will see:
 +
 
 +
qemu-image: Starting VM, booting from CD-ROM
 +
qemu-image: The VM will be run headless, without a GUI. If you want to
 +
qemu-image: view the screen of the VM, connect via VNC without a password to
 +
qemu-image: vnc://127.0.0.1:59xx
 +
 
 +
Type 127.0.0.1:59xx in your VNC viewer client (replace xx with whatever shows up on your build. It changes each time.) This will allow you to monitor the Packer boot commands and determine if you need to make any modifications. If your VNC viewer is configured to use a password or encryption, then turn it OFF.
 +
 
 +
The qemu build process will take a while (about 10 minutes). Good time to clean up the kitchen, respond to an email, make a cup of coffee, etc.
 +
 
 +
==== Build VMWare image ====
  
=== Download & Compile VMWare open-vmdk ===
+
Type:
  
=== Download & Install VMWare ovftool ===
+
sudo make vmware
  
=== Download VyOS Source ===
+
The VMware build is fairly quick. When complete the VMware files are located in packer_build/vmware.
  
=== Generate Private Key ===
 
  
== Build VyOS ==
+
[[Category: Development]]

Latest revision as of 04:22, 25 March 2019

Background

I have been interested in getting VyOS to run as a Google Cloud Compute instance for quite sometime. Unfortunately, the current version of VyOS 1.1.x is based upon Debian 6 which just does not work (unless you jump through many more hoops than I am willing to jump through), so I became curious to see if this would be possible with VyOS 1.2. As I began my investigation into what it would take to compile VyOS 1.2 I noticed that all the documentation was present, but it was not that easy to use (IMHO) and I discovered several "gotchas". The purpose of this HowTo is provide a complete set of instructions on how to compile VyOS 1.2 and point out some of the issues I encounter so that others can do what I did easier and faster.

This HowTo assumes you are familiar with installing Linux and are comfortable working in the Linux shell/command line.

Enjoy.

--Max Abramowitz.

Building VyOS 1.2

Create Build Machine

The first step is to download and build a Debian 8 build machine. You can download Debian 8 "Jesse" from:

Lookout.png Most of the build process can be done from the Linux shell. However, troubleshooting the qemu build process requires vncviewer which requires a graphical desktop environment. The screenshot below show the settings using in my testing.
VyOS build machine initial software configuration

Preliminary Build Machine Configuration

Before installing software you will want to perform some basic configuration of your build machine. Install sudo, add your user account to the sudo group, install open-vm-tools (if your build machine is a VMware virtual machine and install your preferred text editor). Below are the configuration commands I used (these commands were run as root user):

# apt-get install sudo
# adduser <username> sudo
# apt-get install open-vm-tools
# apt-get install emacs
Lookout.png - For some reason the left mouse button does not work with Debian under VMware (at least out of the box). There are a couple of articles on the Internet about this. I was able to login and get a terminal window open using a combination of the keyboard and the right mouse button. Once open-vm-tools was installed the left mouse started working.

Installing sudo and adding your user account to the sudo group is not strictly necessary, but it allows you to do the build process from a non-root / non-privileged account, which is a security best practice.

Installing Required Software Components

Install the basic software needed:

sudo apt-get install git autoconf automake dpkg-dev syslinux genisoimage qemu jq libz-dev zip python3 live-build pbuilder devscripts python3-pystache

There are a few components you will have to download from the Internet in order to build VyOS 1.2:

  • HashiCorp Packer - tool to build automated machine images
  • VMWare open-vmdk
  • VMWare ovftool

Packer

Download Packer (http://www.packer.io/downloads.html). Upload to server. Unzip. Copy to a bin directory.

unzip packer_1.0.2_linux_amd64.zip
sudo cp packer /usr/local/bin/

VMWare open-vmdk

git clone https://github.com/vmware/open-vmdk
cd open-vmdk/
make
sudo make install

VMWare ovftool

You will need a VMWare account to download VMWare ovftool. Goto https://www.vmware.com/support/developer/ovf/. Click Software Download. Download the VMware OVF tool for Linux 64-bit. Upload the bundle to your build machine.

chmod 755 VMware-ovftool-4.2.0-4586971-lin.x86_64.bundle
sudo ./VMware-ovftool-4.2.0-4586971-lin.x86_64.bundle
Follow the prompts to complete the installation

Building .ISO Image & VMware .OVF Files

At this point all the software for building an ISO image should be installed on your build system and you can proceed with downloading the source code and building an ISO image

 git clone https://github.com/vyos/vyos-build.git
 cd vyos-build
 ./configure
 sudo make iso

Go get a cup of coffee. Once the build process is complete the .iso file will be in the build folder

Building qemu image

At this point you have a working .iso image and we can proceed with building the qemu image. Before we build the qemu image you will need to create a private SSL key.

Create privatekey.pem
mkdir key
openssl genrsa -des3 -out key/privatekey.pem 2048
Install VNC Viewer

As mentioned previously, you will need a VNC viewer client to monitor the qemu build process. I used the synaptic package manage to install Tight VNC Viwer.

packer.json

Part of the process of building a qemu image is to boot VyOS, install it in a qemu virtual machine and configure the vm to use DHCP, remove the hardware id for the interface and enable SSH. This is done with packer and a set of boot commands. The boot commands are set/configured in the packer.json file. The packer.json file is located in the scripts directory. The boot commands in the packer.json file relies on somewhat arbitrary timings. My initial experience was that the default timings in the packer.json file did not work with my build machine (the timings were not long enough and the qemu build process failed). I needed to modify the packer.json file and adjust the timings of the boot commands to work with my build environment.

Look at the packer.json file. There is a section labelled "boot_command": under that section are the key commands sent to the qemu vm during the install/configuration process. The documentation for the boot commands can be found at https://www.packer.io/docs/builders/qemu.html (scroll down to the bottom of the page).

The most relevant boot command for your purposes is the <wait> command:

<wait>
wait 1 second.
<wait5>
wait 5 seconds.
<wait10>
wait 10 seconds.
<waitXX>
wait some arbitrary time. Examples:
<wait15s> - wait 15 seconds.
<wait10m> - wait 10 minutes.
<wait1m30s> - wait 1 minute 30 seconds.

Note: - the default delay between keypresses is 100ms.

Actually building qemu image

Open vnc viewer on your build machine.

sudo make qemu

You will see:

qemu-image: Starting VM, booting from CD-ROM
qemu-image: The VM will be run headless, without a GUI. If you want to
qemu-image: view the screen of the VM, connect via VNC without a password to
qemu-image: vnc://127.0.0.1:59xx

Type 127.0.0.1:59xx in your VNC viewer client (replace xx with whatever shows up on your build. It changes each time.) This will allow you to monitor the Packer boot commands and determine if you need to make any modifications. If your VNC viewer is configured to use a password or encryption, then turn it OFF.

The qemu build process will take a while (about 10 minutes). Good time to clean up the kitchen, respond to an email, make a cup of coffee, etc.

Build VMWare image

Type:

sudo make vmware

The VMware build is fairly quick. When complete the VMware files are located in packer_build/vmware.