Mini How-To guide for using and modifying appliance templates.

The appliance templates from the marketplace are a way to sort of make it a bit easier to import a
Qemu virtual machine into GNS3. I've noticed some forum posts expressing difficulty getting these to
work properly, and there was some confusion about whether they would also download the required
software images. Well, I figured some of this out, so I thought I'd share with the rest of the class:

The templates are little text files with the .gns3a extension, and they're formatted like little scripts. The
schema for it can be viewed here:

https://github.com/GNS3/gns3-registry/blob/master/schemas/appliance.json

Since all the information is separated into different categories, and is just plain-text, filenames, md5
checksums, and file sizes, I'm guessing these are just used to auto-populate fields in an actual script
running in the background. But anyway, if you click File→Import Appliance, you'll get a little window
that will have a brief description of the VM you're trying to import, including Vendor, Product Name,
Architecture, Maintainer, etc… Click Next, and you'll be asked which server to upload the appliance to
(local, remote, GNS3-VM), click Next again, and you'll be told whether your system meets the
requirements, and click Next again to reach the Required Files window.

This part of the appliance import is where there's some confusion. On this screen you'll see things like
the appliance name, version, status, filename, size, and four buttons named Import, Download, Create a
new version, and Refresh. I'll go ahead and get Download out of the way:

Download won't necessarily automatically download the required files for you. If you need files
belonging to a paid product (like anything from Cisco or Juniper), or even a free VM that the vendor
requires you to register with them to obtain it, you'll just be sent to their website. If the appliance you
want is something freely available to anyone without the payment/registration requirement, then the
files will be automatically downloaded.

Import can be used if you already have the necessary files on your system, but they aren't located in the
folder with the template file.

Create a new version is used when you have a valid image file for the appliance you want to import,
but it's a different version than the one specified in the template. For example, let's say I'm trying to use
the c7200 template, and I have a v15.2 IOS image, but the template only specified a 12.4 image, then
this is the option you'd use. Otherwise, you'd have to manually modify the template file, like I'll show
in a little bit (it's not hard, just a little time consuming).

Refresh is used when you either used Import, Download, or Create a new version, to update the
window to reflect whether everything is ready to go. If it is, you'll see the status change to “Ready to
install”, and any additional versions you may have created. Click Next to select your Qemu binary,
click Next to see the summary, and click Next again to see any additional information (like login
details), and click Finish to import the appliance. If everything proceeded without errors, you'll be able
to find the VM you imported in the appropriate device section.

One error I saw get posted a good deal was the MD5 mismatch error. That will commonly occur if the
checksum of the file you have doesn't match the one in the template (like a corrupt download).
I've also seen it occur when I modified a template in Windows, and tried using a free MD5/SHA
checksum utility to generate the checksums for it. That utility spit out the checksum with the letters in
all caps, while the template expected the characters to be all lower-case.

Before the Create a new version option was added (when I first started writing this), you had to
manually edit the template if you wanted to use an image file other than the one(s) listed in the
template. This is still totally an option if you want, and you can even modify the template to be used
with a completely new VM that there isn't a specific template for. I'm show an example of modifying a
template to use a different version of an image, how to add multiple versions of a VM to the same
template, and how to modify the template for an entirely new VM. One thing to remember, the
templates want to be in the same folder as the image files on you system, so either keep them together,
or use Import to specify where the image file is in your filesystem.

Modifying the template to specify a single, different image:

Back to my previous example of using the c7200 template, but having a different image file, you would
just make a few changes to the template in a text editor. Mainly, we'll be changing the filename,
md5sum, and the file size. Here's the relevant sections of the template I downloaded last week:

"images": [
{
"filename": "c7200-adventerprisek9-mz.124-24.T5.image",
"version": "124-25.T5",
"md5sum": "6b89d0d804e1f2bb5b8bda66b5692047",
"filesize": 102345240
}
],
"versions": [
{
"name": "124-25.T5",
"idlepc": "0x606df838",
"images": {
"image": "c7200-adventerprisek9-mz.124-24.T5.image"
}
}

You'll notice that this template was created just for that particular 12.4-24 7200 image. I happen to have
a 15.2 image I'd rather use. At the time I was writing this, it was necessary to edit the template and
replace the parts I bolded, but the new Create feature should let you do this while importing the
template. Anyway, since I was writing this in linux, I just opened up a terminal to grab the information
I needed:

128451212 c7200-adventerprisek9-mz.152-4.M6.image

There's the file name and it's size. To generate the md5 checksum I'd need, I ran “md5sum <filename>”
from the same folder:
# md5sum c7200-adventerprisek9-mz.152-4.M6.image
743630cc230ec57f751dc05a57214ef0 c7200-adventerprisek9-mz.152-4.M6.image

There we go. Here's the relevant template sections, after I modified them to use my image:

"images": [
{
"filename": "c7200-adventerprisek9-mz.152-4.M6.image",
"version": "152-4.M6",
"md5sum": "743630cc230ec57f751dc05a57214ef0",
"filesize": 128451212
}
],
"versions": [
{
"name": "152-4.M6",
"idlepc": "0x606df838",
"images": {
"image": "c7200-adventerprisek9-mz.152-4.M6.image"
}
}

All I did was copy and paste the information I collected into their respective fields. I did change the
version number, just because I'm anal-retentive that way. I don't think it's strictly required to do so.
You'll notice that I didn't change the idlepc value. Well, I think there is a way to generate an idlepc
outside GNS3 using dynamips or dynagen, but after farting around unsuccessfully for about 20
minutes, I gave up on that. :)

Now, let's say you are using a template, but you'd like to specify multiple versions of the same VM.
Well, it's really easy to do so. The big kicker is that the configuration for those versions must be the
same. To give you an example of what wouldn't work, is the two versions of TiMOS I have. V12.0R6
requires that I disable KVM, or it'll fail during booting with a crashdump message, and then auto-
reboot. Version 13.0R4 can use KVM, but can only use 1 vCPU, or it'll exhibit the same behavior as
12.0R6. Since they don't really have a common configuration, due to those two issues, I'd have to
create separate templates for them.

Here's the example of when this would work. The different revisions of ASAv can share a common
configuration setup, as should below:

"qemu": {
"adapter_type": "e1000",
"adapters": 8,
"ram": 2048,
"arch": "x86_64",
"console_type": "telnet",
"kvm": "require"
},

Of the three different versions I have, all of them work fine with these settings, so I can go ahead and
add the extra images to the existing template.

Here's what is currently in the lower section of the template:

"images": [
{
"filename": "asav951-201.qcow2",
"version": "9.5.1-200",
"md5sum": "ca071370278ecbd5dfdb1c5a4161571a",
"filesize": 160038912,
"download_url": "https://virl.mediuscorp.com/my-account/"
}
],
"versions": [
{
"name": "9.5.1-201",
"images": {
"hda_disk_image": "asav951-201.qcow2"
}
}
]
}

In addition to 951-201, I also have 952-203 and 942-200. After copying down their filenames, sizes,
and md5sums to a temporary text file, I'll just copy and paste this section a few times in the template:

{
"filename": "asav951-201.qcow2",
"version": "9.5.1-200",
"md5sum": "ca071370278ecbd5dfdb1c5a4161571a",
"filesize": 160038912,
"download_url": "https://virl.mediuscorp.com/my-account/"
}

Now, one thing to note, since we'll be added several more images to this, we'll want to a comma after
the the close bracket on all but the last image in this section (same will be true of “versions”, which
we'll see in a bit).

Here's the modified section, with the extra images added:

"images": [
{
"filename": "asav941-200.qcow2",
"version": "9.4.1-200",
"md5sum": "d8f35f310486878088c7e3f844ea6202",
"filesize": 155975680,
"download_url": "https://virl.mediuscorp.com/my-account/"
},
{
 "filename": "asav951-201.qcow2",
"version": "9.5.1-200",
"md5sum": "ca071370278ecbd5dfdb1c5a4161571a",
"filesize": 160038912,
"download_url": "https://virl.mediuscorp.com/my-account/"
},
{
"filename": "asav952-203.qcow2",
"version": "9.5.2-203",
"md5sum": "4a39fcb63916fed82f83236b21175afa",
"filesize": 169345024,
"download_url": "https://virl.mediuscorp.com/my-account/"
}

I copy 'n pasted in the correct filenames, md5sums, and filesizes, as well as change the version
numbers. Notice that for 941-200 and 9.5.1-200, I added a comma to the close brackets ( },) closing
out their entries. There isn't one for 952-203, since that's the last image in the list.

Next, I'll also copy and paste the “versions” section a few times:

{
"name": "9.5.1-201",
"images": {
"hda_disk_image": "asav951-201.qcow2"
}
},

Again, I'll have to add a comma on the last close bracket around each entry, except for the final one. Be
careful here, since you need to add it to the outermost close bracket, which I highlighted above. After I
added the correct filenames in the hda_disk_image field, and changed their “names”, here's what this
section looks like now:

"versions": [
{
"name": "9.4.2-200",
"images": {
"hda_disk_image": "asav942-200.qcow2"
}
},
{
"name": "9.5.1-201",
"images": {
"hda_disk_image": "asav951-201.qcow2"
}
},
{
"name": "9.5.2-203",
"images": {
"hda_disk_image": "asav952-203.qcow2"
 }
}
]

After this, just save the file, or save it as a new file (remember that it needs that .gns3a extension!).
Don't forget that the template really wants to be in the same folder as the image files, so if it isn't, you'll
need to use Import to point them out to the wizard, and then hit Refresh.

As my final example, I'll show how I modified an existing template to use a VM that isn't present in
Marketplace yet. If you read my post about adding EXOS to GNS3, you saw that I created a Qemu
VM of it, since there isn't one available on their github page yet. What I'll do is take the vIOS-L2
template, and then modify it enough for use with this VM instead.

The first thing I did was just change all the text information in the top section, so that it reflected that
this was an EXOS from Extreme Networks instead of vIOS from Cisco, and changed the URLs. I'll
omit most of this for brevity. Even if you don't feel like changing all that information, there are still
two you should change: The name of the appliance, and the category it goes into.

"name": "Cisco IOSvL2",

"category": "multilayer_switch",

Since this is still a multilayer switch VM, I can leave that alone (if this were a router or firewall, I'd
definitely want to change this). Changing the name is important, so you can uniquely identify this VM.

With that out of the way, here are the parts we're really concerned about:

"usage": "There is no default password and enable password. There is no default configuration
present.",
"port_name_format": "GigabitEthernet{1}/{0}",
"port_segment_size": 4,
"qemu": {
"adapter_type": "e1000",
"adapters": 16,
"ram": 768,
"arch": "i386",
"console_type": "telnet",
"kvm": "require"
},
"images": [
{
"filename": "vios_l2-adventerprisek9-m.vmdk.SSA.152-4.0.55.E",
"version": "15.2.4055",
"md5sum": "1a3a21f5697cae64bb930895b986d71e",
"filesize": 96862208,
"download_url": "https://virl.mediuscorp.com/my-account/"
}
],
"versions": [
{
 "name": "15.2.4055",
"images": {
"hda_disk_image": "vios_l2-adventerprisek9-m.vmdk.SSA.152-4.0.55.E"
}
}
]
}

To tailor this to EXOS, here's a list of the changes I'll make:

1) Change the usage field, to tell how to login

2) Add a “first_port_name” field, since “eth0” will be the mgmt interface
3) Change the port_name_format, since it isn't applicable
4) Remove the port_segment_size, since there isn't linecards here.
5) Change the RAM to 256MB
6) Change the interface count to 12 (the vm seems to only be capable of 12 ports)
7) Change the architecture to x86_64
8) Add the “options” field with “-cpu host”, as some type of cpu needs to be specified.
9) Change the images, filenames, versions, size, checksums, and remove the download_url entry.

Here's what all that looks like, with all the changes I made in bold:

"usage": "Login as admin (no password) once AAA is available on the master node ",
"first_port_name": "Management",
"port_name_format": "Port{0}",
"qemu": {
"adapter_type": "e1000",
"adapters": 13,
"ram": 256,
"arch": "x86_64",
"console_type": "telnet",
"kvm": "require",
“options”: “-cpu host”
},
"images": [
{
"filename": "exospc-16.1.3.6.img",
"version": "16.1.3.6",
"md5sum": "46d11694174ebb550857125b801aacc1",
"filesize": 177078272
}
],
"versions": [
{
"name": "16.1.3.6",
"images": {
"hda_disk_image": "exospc-16.1.3.6.img"
}
}
 ]
}

After this, just save the template as a new file, and you're ready to import it. At some point, Extreme
has a qemu VM version planned to be made available on their github page, which is free to anyone to
download, so a template will be made for it. You could also use this for pretty much anything else
you'd like, provided it can be run as an IOS/IOU/Qemu device.

Well, that's pretty much it, so have fun with this! :)