Protocol Handlers
=================

Overview
--------

In order to use the clickable URLs generated by the Breakout utility when
running in UI mode, we need to configure URL Handlers into the operating system
so Firefox, Chrome and other browsers can handle these links.

Those Telnet and VNC URL handlers are usually not present by default on Windows,
macOS or Linux.

These instructions have been tested using Windows 10 but we can assume other
Windows version will also work. For other operating systems, similar
instructions are available which will be added to this document over time.


For Windows 10
--------------

The following code snippets are Windows registry files that, when used properly,
will make the modification required for the features outlined above.

The proper way to perform these changes is to open up a text file in Windows
using e.g. Notepad, copy and paste the following sections into the text file,
save those files to disk and then renaming the extension of the files from
``.txt`` to ``.reg``.

Once the files are saved on the target computer, right click on each of the
files and select "Merge".

After merging the registry changes, close the browser and re-open the Breakout
utility. Now, when clicking on a Telnet or VNC link it should automatically open
Putty to the host and port from the connection URL from the Breakout lab detail
page.

This document only outlines the use of Putty and UltraVNC as the Telnet and VNC
clients, respectively. Changing the path will allow testing of other clients
like SecureCRT but that's outside the scope of this document.

In this particular case, the location of Putty was ``C:\Program
Files\PuTTY\putty.exe`` and ``C:\Program Files\uvnc
bvba\UltraVNC\vncviewer.exe``

By replacing the Putty application ``.exe`` files in the examples below, other tools
like SecureCRT should be usable as well.

.. warning:: Changing the registry can lead to a non-working system. We recommend
   to backup your registry and / or your entire computer so that the previous
   state can be restored, if needed.

Telnet URL Handler
******************

.. code-block:: text
    :linenos:

    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"


SSH URL Handler
***************

.. code-block:: text
    :linenos:

    Windows Registry Editor Version 5.00

    [HKEY_CLASSES_ROOT\ssh]
    @="URL:SSH Protocol"
    "URL Protocol"=""
    [HKEY_CLASSES_ROOT\ssh\shell]
    [HKEY_CLASSES_ROOT\ssh\shell\open]
    [HKEY_CLASSES_ROOT\ssh\shell\open\command]
    @="C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe -Command \"$uri = [System.Uri]'%l';&\"${env:ProgramFiles}\\PuTTY\\putty.exe\" $uri.GetComponents([System.UriComponents]::UserInfo -bor [System.UriComponents]::Host, [System.UriFormat]::UriEscaped)\""


VNC URL Handler
***************

.. code-block:: text
    :linenos:

    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\\uvnc bvba\\UltraVNC\\vncviewer.exe\" !URL:*://=!\""


Chrome Bypass Protocol Prompt
*****************************

Having the URL handlers in place is OK but Chrome will prompt the user each time
they click on a URL unless we bypass the prompt by adding the protocols into the
protocol whitelist.

Telnet
^^^^^^

.. code-block:: text
    :linenos:

    Windows Registry Editor Version 5.00

    [HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Google\Chrome\URLWhitelist]
    "1201"="telnet:*"

VNC
^^^

.. code-block:: text
    :linenos:

    Windows Registry Editor Version 5.00

    [HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Google\Chrome\URLWhitelist]
    "1202"="vnc:*"

 

For macOS
---------

To be added.

For Linux
---------

To be added.


References
----------

Based on work found on StackOverflow_

Similar, also includes instructions for Linux and macOS_

.. _StackOverflow: https://stackoverflow.com/questions/29523066/how-do-i-get-internet-explorer-to-handle-custom-protocol-handlers-correctly
.. _macOS: https://support.shotgunsoftware.com/hc/en-us/articles/219031308-Launching-applications-using-custom-browser-protocols
