Install DevTunnelInstaller

Learn how to install DevTunnelInstaller, the DevTunnel connection software, on Windows, Mac, and Linux (Debian only) workstations.

Known limitations

The current release of DevTunnel has the following limitations:

  • DevTunnel works with Java 17 and earlier.
  • If a device is directly connected to the development station when starting the DevTunnel session, DevTunnel will block this device and it will not be accessible from any tool.
  • When Chrome inspect is active in a DevTunnel session, the following actions in the Perfecto Plugin may fail:
    • Object Spy - element click
    • Object Spy - find elements
  • When using XCTest, on a DevTunnel-connected device, in Xcode, do not perform any interactive operations on the device. Such operations will stop the running XCTest package.

  • DevTunnel is supported on all devices. However, when used on a Windows machine, DevTunnel is supported only on Android devices. When used on a macOS machine, DevTunnel is supported on both Android and iOS devices.

Prerequisites

Before installing and using the DevTunnel feature on your development station, verify the following system requirements:

  • The DevTunnel Installation package requires Administration privileges on the development station.

  • Java Development Kit (JDK):

    • Windows and Mac workstations: JDK version 1.7 or later is installed. The highest supported Java version is version 17.

      Important: On Mac workstations, verify that no other Java versions, especially x86 Java, or Java versions from different vendors are present in the JAVA_HOME folder on your Mac machine.

    • Linux workstations: JDK version 8 or later is installed. The highest supported Java version is version 17.

  • Windows workstations only: .NET Framework version 4.6 or later is installed.

    If the .NET framework is not pre-installed, it will be installed as part of the DevTunnel installation package

  • Linux workstations only:

    • USB multiplexer (usb-mux) is installed with the libimobiledevice-dev library. To install the library, run the following command:

      Copy 
      sudo apt-get install -y libimobiledevice-dev

    • (Optional) If you intend to run DevTunnel CLI scripts from the command line, cURL is installed. Run the following command to install cURL:

      Copy 
      sudo apt-get install curl

  • To run Appium on the machine, the version needs to match the Appium version in the Perfecto cloud.

  • The configuration of your local network must employ the following:

    • A transparent proxy to connect to the Perfecto Lab. Verify that all Lab sites are included in the allow list of the proxy.

    • An explicit proxy with credential authentication to connect to the Perfecto Lab. Follow the procedure on the Proxy Configuration page.

    • Web inspection. Verify that all Perfecto Lab sites are included in the allow list of the proxy.

  • If your company maintains a strict firewall policy, contact your IT department and ask them to add the following URLS to the allow list. For the installation to succeed, these URLs must be allowed and accessible by DevTunnelInstaller.

    • <your_cloud>.api.perfectomobile.com

      For example: demo.api.perfectomobile.com

    • https://perfecto-mobile-devtunnel-config-provider-production.s3.amazonaws.com/

Installation package

Perfecto provides an installation package that installs different software elements onto your computer. These elements allow you to:

  • Establish a secure connection between your development computer and the Perfecto Lab Handset Server.
  • Make the Android debugging tools identify the Perfecto device as connected to the development station.

Following is a list of the third-party packages that are part of the DevTunnel installation:

  • STunnel (www.stunnel.org): Establishes a secure tunnel from a local port to a remote DevTunnel server on port 443.
    Location: DevTunnel installation folder (Default: C:\Program files (x86)\DevTunnel\stunnel)

  • Plink (www.chiark.greenend.org.uk/~sgtatham/putty): Establishes a secure channel over the STunnel layer.
    Location: C:\Program Files (x86)\DevTunnel(default)

  • Subinacl (https://www.microsoft.com/en-us/download/details.aspx?id=23510): A Microsoft binary used by the installer to lower the DevTunnel windows service permissions.

  • Perfecto Binaries:

    • DevTunnel Windows Service: .NET binary. The DevTunnel client that starts up when a session is started. Responsible for DevTunnel initialization.
    • DevTunnelHelper: .NET binary used to bridge between browser and DevTunnel Windows Service.
    • External Dlls:

  • STunnel (www.stunnel.org): Establishes a secure tunnel from a local port to a remote DevTunnel server on port 443. Location:/usr/local/etc/stunnel 

  • Perfecto Binaries:

    • PerfectoDevTunnel.jar: Client that starts up when a session is started. Responsible for DevTunnel initialization.
    • DevTunnelHelper.app: macOS application used to bridge between browser and PerfectoDevTunnel.jar.
    • PerfectoADBHelper.jar: Detects client ADB version for compatibility improvements.
    • Perfecto_iOS: Used to initiate iOS DevTunnel sessions.
    • Perfecto_Android.sh: Used to initiate Android DevTunnel session.
    • DevTunnelRelay.jar: DevTunnel service that directs traffic to proper connected device.

  • Perfecto Binaries:

    • install.sh: Used to install DevTunnel.

    • uninstall.sh: Used to uninstall DevTunnel.

    • Perfecto-opener.desktop: Defaults Perfecto URI calls to open-perfecto.sh so that the browser can open the correct script when activating DevTunnel from Perfecto.

    • open-perfecto.sh: Reads the parameters from Perfecto and then executes the PerfectoDevTunnel.jar client with the those paramters.

    • device-parser.py: Opens the base-64-decoded JSON file from Perfecto and modifies the da value to match with Android or iOS (values 0 or 1). By default, Perfecto sends the value 0 (Android) for all devices when not browsing from a Mac machine. This file is executed by open-perfecto.sh.

    • DevTunnelRelay.jar: DevTunnel service that directs traffic to proper connected device.

    • PerfectoDevTunnel.jar: Client that starts up when a session is started. Responsible for DevTunnel initialization.

Download the installation package

  1. If you use any of the following anti-virus software tools, add PerfectoInstaller.exe to the anti-virus exception list on your workstation. Otherwise, the virus detection of these tools may falsely identify a virus associated with the installer package.

    • Avira
    • Baid
    • Endgame
    • Invincea
    • Qihoo-360
  2. In the Manual Testing view, open a device.
  3. On the device toolbar, click the Connect DevTunnel icon .

  4. In the DevTunnel dialog box, click Download DevTunnelInstaller.

    The download tool identifies the target development station's operating system (Windows or Mac) and downloads the proper installation package.

  5. Save the file on your local development station.

Install the package on the development station

Depending on your operating system, you may need to perform additional steps before you can run the installer. Click an operating system below to view the relevant steps.

  1. Retrieve your security token from the Perfecto UI.

    1. In the Perfecto UI at <YourCloud>.app.perfectomobile.com (where YourCloud is your actual cloud name, such as mobilecloud), click your user name and select My security token. 

    2. In the My security token form, click Generate Security Token.

    3. Click Copy to clipboard. Then paste it into any scripts that you want to run with Perfecto. 

    4. Click Close.

  2. Activate the installation package and, if prompted, confirm the permission to install the software.

  3. In DevTunnelInstaller, perform the following steps:

    1. To accept the Perfecto License that provides the terms of using this software, click I Agree.

    2. Select an installation folder and click Next.

      The default installation folder is C:\Program Files(x86)\DevTunnel, but you can change this location by clicking the Browse button.

    3. Enter your Perfecto security token and click Next.

    4. Enter the name of your Perfecto cloud as it appears in your cloud URL (<cloudname>.app.perfectomobile.com), such as mobilecloud or demo, and click Next.

    5. When prompted if you use a proxy:

      • If you use a proxy: Click Yes.

        Provide your proxy IP address and port, and then click Next.

        If your proxy requires authentication, click Yes and provide the proxy username and password. Then click Install. Otherwise, click No. The installation starts immediately.

      • If you don't use a proxy: Click No. The installation starts immediately.

      A progress bar indicates the progress of the installation process.

    6. When the installation is complete, click Close.

  1. Open a terminal window and run the following command. This command creates a new folder (usr/local/etc/devtunnel) that contains the following files: 

    • token.txt

    • cloud.txt

    Copy 
    mkdir -p -m 700 /usr/local/etc/devtunnel && install -m 777 /dev/null /usr/local/etc/devtunnel/token.txt && install -m 777 /dev/null /usr/local/etc/devtunnel/cloud.txt

  2. Retrieve your security token from the Perfecto UI.

    1. In the Perfecto UI at <YourCloud>.app.perfectomobile.com (where YourCloud is your actual cloud name, such as mobilecloud), click your user name and select My security token. 

    2. In the My security token form, click Generate Security Token.

    3. Click Copy to clipboard. Then paste it into any scripts that you want to run with Perfecto. 

    4. Click Close.

  3. Edit the text files:

    • Open the file /usr/local/etc/devtunnel/token.txt and paste the security token into it. Then save and close the file.

    • Open the file /usr/local/etc/devtunnel/cloud.txt and and insert the name of your Perfecto cloud. For example, if your cloud is ‘demo.app.perfectomobile.com', you should write 'demo’ in the cloud.txt.

    Important: The text edit program you use may change the first letter in the file to uppercase. If this is the case, manually change it back to lowercase. The installation process is case sensitive and could fail if the capitalization is not accurate.

  4. Activate the installation package. Then perform the following steps in the Install Perfecto DevTunnel wizard:

    1. In the Introduction panel, click Continue.

    2. Read the license agreement and click Continue. Then click Agree to accept the Perfecto License.

    3. In the Destination Select panel, click Continue to install the software packages on the computer's default installation device (Macintosh Hard Drive).

    4. In the Installation Type panel, click Install to install the software at the default file locations. Do not change the installation location.

    5. If prompted for a username and password to confirm the installation, enter your credentials and click Install Software.

      The Installation panel indicates the progress of the installation process. As part of the installation process, several packages are installed (see Installation package).

    6. If prompted to allow STunnel to accept incoming network connections, click Allow.

    7. If prompted to restart one or more applications, click Restart Apps or, if you want to restart them later, click Skip. For more information, see Mac | Restart applications.

    8. In the Summary panel, click Close to complete the installation.

Mac | Restart applications

As part of the DevTunnel installation, Perfecto supplies a Relay service that affects how different applications identify the devices connected to the Mac workstation. This affects any applications, for example Xcode, that may need to access a connected device.

During the installation process, DevTunnel checks whether any of the affected applications are active and requests that they be restarted before using them with the connected devices.

Things to know about restarting applications:

  • If you intend to use your IDE or Safari Web Inspector with a device connected through DevTunnel, you should elect to restart the app.
    In any case, the application must be restarted before using a DevTunnel connected device.
  • If you do not intend to use any of the listed applications with DevTunnel devices, you can skip the automatic restart.
  • If you install DevTunnel from a Safari session and you elect to restart Safari, as a result of the prompt, your Perfecto Lab session will be closed and you will need to reconnect and reopen the device. However, when connecting to DevTunnel, you do notneed to reinstall the service.
  • The list of applications to restart may include applications that are running background services.

Depending on your permissions on the Linux machine, you may need to run both terminal commands by sudo.

  1. Open a terminal window and run the following command. This command creates a new folder (usr/local/etc/devtunnel) that contains the token.txt file. 

    Optionally, you can add the security token as a second parameter when you run the installer. If this is what you prefer, you do not need to perform this step.

    Copy 
    mkdir -p -m 700 /usr/local/etc/devtunnel && install -m 777 /dev/null /usr/local/etc/devtunnel/token.txt

  2. Retrieve your security token from the Perfecto UI.

    1. In the Perfecto UI at <YourCloud>.app.perfectomobile.com (where YourCloud is your actual cloud name, such as mobilecloud), click your user name and select My security token. 

    2. In the My security token form, click Generate Security Token.

    3. Click Copy to clipboard. Then paste it into any scripts that you want to run with Perfecto. 

    4. Click Close.

  3. Open the file /usr/local/etc/devtunnel/token.txt and paste the security token into it. Then save and close the file.

    Optionally, you can add the security token as a second parameter when you run the installer. If this is what you prefer, you do not need to perform this step.

  4. Extract the PerfectoInstaller.zip file.

  5. In the terminal window, change directory to the directory that contains the extracted installer files, and then run the following command:

    Copy 
    ./install.sh <cloud-name>

    If you did not include the security token in the dedicated file in step 3, run the command by adding the security token as a second parameter after the cloud name, as follows.

    Copy 
    ./install.sh <cloud-name> <security-token>

Uninstall DevTunnel

To uninstall DevTunnel, perform the instructions for your operating system.

  1. Go to Start > Perfecto > Uninstall DevTunnel.

  2. When prompted, click OK to confirm that you want to uninstall DevTunnel. 

  3. When the installation is complete, click Close.

  • Run the supplied uninstall.sh shell script in sudo mode. By default, the shell script is installed in the /usr/local/etc/stunnel folder.

    Copy

     

    sudo /usr/local/etc/stunnel/uninstall.sh

  • Run the supplied uninstall.sh shell script. By default, the shell script is installed in the /usr/local/etc/stunnel folder.

    Copy 
    ./uninstall.sh