Appliance Templates.pdf 3x5p48

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 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 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, , Create a new version, and Refresh. I'll go ahead and get out of the way: won't necessarily automatically 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 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 ed. 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, , 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 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 ).

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 , 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 ed 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 ” 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 autoreboot. Version 13.0R4 can use KVM, but can only use 1 vU, 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, "_url": "https://virl.mediuscorp.com/my-/" } ], "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, "_url": "https://virl.mediuscorp.com/my-/" } 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, "_url": "https://virl.mediuscorp.com/my-/" }, {

"filename": "asav951-201.qcow2", "version": "9.5.1-200", "md5sum": "ca071370278ecbd5dfdb1c5a4161571a", "filesize": 160038912, "_url": "https://virl.mediuscorp.com/my-/" }, { "filename": "asav952-203.qcow2", "version": "9.5.2-203", "md5sum": "4a39fcb63916fed82f83236b21175afa", "filesize": 169345024, "_url": "https://virl.mediuscorp.com/my-/" } 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 ( 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 and enable . 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, "_url": "https://virl.mediuscorp.com/my-/" } ], "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 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 “-u host”, as some type of u needs to be specified. 9) Change the images, filenames, versions, size, checksums, and remove the _url entry. Here's what all that looks like, with all the changes I made in bold: "usage": " as (no ) 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”: “-u 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 , 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! :)