The “Breakout Tool” in CML allows you to use Putty and VNC to control lab devices, but it is risky to config!
The CML 2 VM labbing environment opens devices in a rather rigid and difficult to work with embedded console window like you would see in a DevNet learning lab on developer.cisco.com, fortunately they do provide a means to use local tools such as Putty and VNC to access the Topology, unfortunately you run the risk of bricking your PC doing it!
For this reason, before proceeding to start creating and merging registry files, I would highly recommend cloning your hard drive if you can’t afford to lose all the files on your PC when a registry edit bricks your PC!
Upon working with this embedded Console window for awhile I quickly realized it was not a long term solution for me, and that risking the PC brick was worth being able to use Putty, but you have been warned if you proceed.
I am so glad Cisco included this Breakout Tool with a possible PC brick, rather than avoiding it being an issue!
CML is a great tool, but the embedded console is painful to work in, and I really think Cisco deserves a huge tip of the hat to post a computer registry hack type of tool to allow labbers to use a Telnet client! Thank you Cisco!!!
Now lets get this install over with and start using Putty!
First things first, once you are in your CML 2 “Workbench” dashboard (in the web GUI) you will click on “Tools” and then select “Breakout Tool” where a short scroll down will show different install files for the Tool itself, kind of:
Note that this is for CML 2 using Windows 10 exclusively in this demo, I would not be able to or even want to answer questions about how to do things, as it was very iffy installing this on my own machine 🙂
Step 1 – Download the breakouttool.exe file, add ” ui” to the .exe in the file properties, and some other stuff
I downloaded the windows .exe breakouttool file, moved it to its own folder directly on the C: drive, and from there you need to right click the file and select “Create Shortcut” and then go into that shortcut and add ” ui” to the end of the files .exe extension – There is a space between .exe and ui such as: “…tool.exe ui” that is added within the Shortcut Properties.
Below is a screenshot of the folder containing the original executable file, its shortcut files properties with the ” ui” append circled and also the “Change Icon” highlighted as I would recommend picking a custom icon to help you spot it:
Once the shortcut of the .exe file was created with ” ui” on the end of the file name in Properties, I pinned it to Taskbar:
Note that I did not type anything into the Shell, I just clicked that icon, and it popped up this screen, also I gave it a custom icon in the Shortcut properties which is why it looks like a little PC so I could identify it in my task bar.
Once the “Breakout Tool” Shell is launched a YAML file will be created automatically called labs.yaml, which will contain all of the CML 2 labs once it is properly configured, though this might error out until configuration is complete.
Step 2 – Browse to the Breakout Tool URL in the Shell screenshot, click “Configuration” and enter as shown
What needs to be changed is the Controller Address to the IP Address you browse to for access to the Web GUI, disable “Verify TLS Certificate” and Enable “Populate all nodes”, and enter your Web GUI admin credentials and save.
All other values can be left the same for ports and the ::1 listener addy, and the labs.yaml should now exist within the folder that the original breakouttool.exe file / shortcut file resides in, and is used to pull labs to populate the “Labs” tab on the left hand side towards the top of the page.
At this point labs will likely not be populating as there is still some more work to do, and this is where it gets a bit more sketchy, and a lot more risky – So really be sure you are prepared to lose your data if you don’t backup your PC!
Step 3 – Download Putty and VNC Viewer, and get ready to create and modify your Windows 10 Registry!
It’s not THAT big of a deal to “Merge” some files into your registry, but I’ve been on the one with a bricked PC hoping it wouldn’t happen in the past, so you really need to back up or clone that HDD / SSD or be prepared for a bad time!
The Registry Items being added are “Protocol Handlers” that allow the “Breakout Tool” to create hot-links for lab devices to use hot-links on the “Lab” page to open devices in Putty or VNC from your desktop – So very worth the risk to me!
The first step to this process is to download Putty and VNC Viewer, open the executable and allow them to install to your PC, once installed right-click both executable files -> Open Properties -> Copy their file path on the PC for use when creating the Registry files to Merge into your PC’s registry.
Below is the exact registry files copied from the Breakout Tool documentation that I pasted into Notedpad, adjusted the file path slightly so that it is pointing to where my local Putty and VNC reside or they won’t open properly, and saved them as a “.reg” instead of a “.txt” and saved them to the Local PC to perform the “Merge” (I don’t think it matters where you save the files as long as its on the PC file system).
Below are the file name / title exactly as it needs to be spelled, and the contents needed in the file:
Telnet URL Handler.reg
Windows Registry Editor Version 5.00
[HKEY_CLASSES_ROOT\telnet]
@=”URL:Telnet Protocol”
“EditFlags”=dword:00000002
“FriendlyTypeName”=”@C:\Windows\System32\ieframe.dll,-907”
“URL Protocol”=””
[HKEY_CLASSES_ROOT\telnet\DefaultIcon]
@=”C:\Windows\System32\url.dll,0″
[HKEY_CLASSES_ROOT\telnet\shell]
[HKEY_CLASSES_ROOT\telnet\shell\open]
[HKEY_CLASSES_ROOT\telnet\shell\open\command]
@=”\“C:\Program Files\PuTTY\putty.exe\” %1″
Telnet.reg
Windows Registry Editor Version 5.00
[HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Google\Chrome\URLWhitelist]
“1201”=”telnet:*”
VNC URL Handler.reg
Windows Registry Editor Version 5.00
[HKEY_CLASSES_ROOT\vnc]
@=”URL:VNC Protocol”
“URL Protocol”=”http://www.uvnc.com/”
[HKEY_CLASSES_ROOT\vnc\DefaultIcon]
[HKEY_CLASSES_ROOT\vnc\shell]
[HKEY_CLASSES_ROOT\vnc\shell\open]
[HKEY_CLASSES_ROOT\vnc\shell\open\command]
@=”cmd.exe /V /C \”set URL=%1& start \”\” \”C:\Program Files\RealVNC\VNC Viewer\vncviewer.exe\” !URL:*://=!\””
VNC.reg
Windows Registry Editor Version 5.00
[HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Google\Chrome\URLWhitelist]
“1202”=”vnc:*”
Highlighted in Blue are the file paths that will need to be slightly adjusted to match the file path that was retrieved from Putty and VNC Properties after installed, it needs to match your exact file path which may differ!
The first file is the Protocol Handler Registry Item, and the smaller Registry item below it that corresponds with Telnet and VNC are to “Whitelist” Google Chrome to to open Putty and VNC.
Then to complete this process you will go to the location of your 4 registry files, highlight them and right click the group of files, and select the option “Merge” and click yes through any warnings or Windows firewall messages to add the new registry items and you are almost ready to start using a Putty to connect to CML:
Once all of these successfully install into the Registry, I shut down my lab / closed the Breakout Tool Shell / closed all Google Chrome browser windows to completely relaunch everything fresh, one thing to note that devices do have to be powered on and reachable by IP for the hot links to open them (so be sure to power on the lab your trying to Putty to).
The lab is mostly turned on except for Trex at the top:
I re-launch the “Breakout Tool” Shell that is pinned to the Taskbar:
I open a second tab in Google Chrome and browse to http://%5B::1]:8080 to the Breakout Tool web GUI:
In the “Labs” tab I click the refresh button, and my “Multicast Lab” shows up, and the entire new column that I tried to highlight now become clickable to bring you to that lab, and before clicking into the labs page to open Putty / Telnet windows via hot-link I slide the Status to “On” and proceeded to the “Lab” page to view my lab devices.
Then once I click anywhere on that yellow column it bring me to my Multicast Lab page, and I now have links for both Putty and VNC to click, though I have actually not gotten VNC working yet as I only really NEED Putty / Telnet:
R1 now opens via the circled hot-link to a Telnet session on the Putty application installed locally on my PC! 🙂
The “Breakout Tool” Shell will need to remain open to allow the Breakout Tool to work, as can be seen here:
You are now off to the races, there is no configuration that needs to be done within the application Putty, as long as the Registry file has the correct file path to open it, the hot-link will pop it open automatically!
Some final notes and a video that helped me understand where to click around when I was installing this
I did create the Registry File for SSH, however Windows 10 registry does not allow entries to contain scripts, so the SSH Registry that can be found within CML -> Tools -> Breakout Tool -> Documentation / Downloads.
So if you noticed that I only installed Putty but not SSH, the Registry item in CML contains a script which Windows 10 will not accept and I only really need Telnet to be a happy labber.
Several parts of this configuration threw local PC firewall alerts, so if something is not popping up or working as expected, I would first check the local firewall logs and I actually disabled the local Admin on my machine so no permissions would block things from working due to Admin rights being an issue.
I also watched several Youtube videos, and found this one the most straight forward and helpful, as the Breakout Tool documentation can be very confusing and even though this person is on a Mac using SecureCRT the install should take about as long as this person demonstrate without a whole lot of Powershell / Bash / messing around in file properties:
I may have missed or skimmed over some things in that explanation, please feel free to leave me a reply on this page with questions or if you have me on LinkedIn or my Discord server please shoot me a PM with questions or assistance!
Again the person in that video is using a Mac, the Breakout Tool documentation looks maybe a little older than its current form, but it was a good demo of how long and complex the install should be – About 10-15 minutes unless you are running into a wide range of possible issues that I ran into at times and used basic steps like running something as an Admin, closing out of everything and relaunching it, googling the error, etc.
With that, I have had quite enough of “Breakout Tool” talk for one night, long live Putty! 🙂
The DEVNET GRIND! 