Install the connector on a Linux machine

The Device Connector is a standalone component for connecting devices to Digital Lab. You can also install the connector as a standalone component on a Linux machine, and configure it to connect to the Digital Lab server. Devices connected to distributed connector machines become part of the Digital Lab device lab.

In this topic:

Before you start

Before installing or updating the connector:

• Refer to the support matrix for supported Linux versions. For details, see Support matrix. Note: Ubuntu is supported only on UFT Digital Lab version 24.2 and ValueEdge Digital Lab.

• Check that your machine complies with the recommended system requirements and that your devices are supported. For details, see Connector requirements in the Support matrix, Connect devices to Digital Lab, and Installation and configuration best practices.

For a new installation only:

1. Make sure that a Digital Lab server is not already installed on the machine.

2. The server should be accessible to the connector.
   To check the connection run the following curl command and check that you get a 200 OK status:

   curl -I http/s://<Digital Lab server IP address>:<port>

3. If Nginx is already installed on the connector machine, remove it before installing the Digital Lab connector.

4. Obtain an access key for the connector from the Digital Lab server.

   • Admin user: Select the Connectors tab. Click Generate New Key and provide a name, type (Connector), expiration date, description (optional).
   • Non-admin user: request one from your admin. Select Contact Your Admin from the Help menu (upper right).

5. CentOS 7.6 -7.9 new installation: X11 forwarding is required.

   1. Install required packages:
      
      
      Copy code

      yum install -y xorg-x11-server-Xorg xorg-x11-xauth xorg-x11-apps

   2. Enable X11 forwarding.
      
      

      Open the SSH configuration file:
      

      Copy code

      vi /etc/ssh/sshd_config

      
      

      Uncomment or add the lines below:
      

      Copy code

      X11Forwarding yes

      
      

   3. Restart the SSH service:
      

   Copy code

   systemctl restart sshd

   
   

Back to top

Considerations for Ubuntu

Ubuntu is supported only on UFT Digital Lab version 24.2 and ValueEdge Digital Lab.

There are a number of considerations to be taken into account when installing the Linux connector on Ubuntu.

Consideration	Details
Version support	Only Ubuntu version 22.04.3 (LTS) is supported.
Installation type	Ubuntu Normal installation and Ubuntu minimal installation are supported. Ubuntu Pro is not supported.
Editions	Ubuntu Desktop and Ubuntu Server are supported.
CPU	Only X86_64 architecture is supported.
Permissions	Installation requires sudo permissions

Back to top

Considerations for iOS 17

 A number of considerations should be taken into account before installing the Linux connector.

Considerations	Details
Connector machine OS	UFT Digital Lab version 24.2 and ValueEdge Digital Lab: iOS 17 is currently supported only on Mac and Linux Ubuntu (22.04.3) connectors. For details on installing on a Mac connector, see Install the connector on a Mac machine. UFT Digital Lab 23.4: iOS 17 is currently supported only on Mac connectors.
Internet connection	To fetch a signature key from Apple from time to time, the connector machine must have access to the following: http://gs.apple.com UFT Digital Lab 23.4: time.apple.com devimages-cdn.apple.com itunes.apple.com itunes.com developerservices2.apple.com developerservices2.v.aaplimg.com OpenText recommends allowing access to all *.apple domains
Support	The following are not supported for iOS 17: Connecting AWS Device Farm and WeTest devices. Force quit application

Back to top

Download the connector

Download the connector in one of the following ways:

• For admins, Select Download Connector in the Connectors page.
• For a non-admin user, select Download Connector from the Help menu of the Digital Lab console.

Back to top

Install the connector

The standalone connector for Digital Lab can be installed as a full installation, or as an upgrade to an existing installation of the connector. The installer checks what files are already present, and installs or updates the relevant files.

1. On your Linux machine, log in as root . Ubuntu: Requires sudo permissions to install.
2. Copy the file to your Linux machine and extract the installation files: 
   unzip <name of Linux connector installation file>.zip –d <Target directory Name>
3. Change directory to the target directory:
   cd <Target directory name>/
4. Run the connector installer:
   ./<install_connector-x64 file name>.bin
5. Read the License Agreement, and select Y to accept the terms and proceed with the installation. Choose an installation folder, and a local folder for temporary files. Fill in the information or answer the questions in each of the Installation sections following these guidelines:
   

User configuration
Use an existing Linux OS user, or click n to create the default user. Specify the password for this user.
Authentication
Enter your credentials. Enter the access key provided by your admin. Digital Lab SaaS: The SSL Enabled option should be selected.
If connecting over a proxy, select Server address in the proxy section, and specify the server, port, and credentials if required.
Connector configuration
Provide a meaningful name for the connector, as this allows you to effectively filter devices based on connector names. Enter the Connector's IP address (if the IP is static) or FQDN, or accept the defaults.

For details on how to change the configuration after the installation, see Change the configuration of the connector.

Review the pre-installation summary and press Enter to continue with the installation of the connector.

Back to top

Connect and verify devices

1. If you have not already done so, make sure to follow the steps for initial device configuration when connecting Android and iOS devices.
2. Connect the device to the connector machine using a USB cable. On some devices, when you connect the device, there may be notification, trust, or location pop-ups. Accept these pop-ups.
   
3. Wait until the Agent is running on the device.

4. If the Agent does not start up on the device, verify that the devices are recognized:
   

   Android devices

   Run the following command on the Linux connector machine (If you are a root user, change directory to /opt/UFTDigitalLab/connector/android-sdk-linux/platform-tools):
   

   ./adb devices

   All your connected devices should be listed. The status of the device should be "device" and not any other state, for example "unauthorized".

   Tip: If you are connecting with a C-Type USB device, such as One Plus, Nexus 5, etc, the idVendor value may not have been recognized.
   Workaround: Run dmesg to obtain the idVendor value, beginning with 0x. Log in as the user specified during installation. Run the sudo ~/add_android_vendor.sh <idVendor> script.

   iOS devices

   1. Go to:
      /opt/UFTDigitalLab/Connector/libimobiledevice/linux/
      
   2. Run ./idevice_id –l

   
   The result of this command should be a list of devices IDs (UDID). If the command returns an empty result or ERROR message, try the following:

   1. On the Digital Lab server or connector machine, log in as root .
   2. Locate the process ID of “usbmuxd”"
      ps aux | grep '[u]sbmuxd'
   3. Kill the process:
      kill –9 <processID>
   4. Start usbmuxd again:
      usbmuxd
   5. Run idevice_id –l again to see if the device is recognized.
      

   If the devices are connected correctly, try to manually launch the Digital Lab Launcher app. If you see an Untrusted App Developer notification:
   

   • Click Trust.
   • Disconnect the device.
   • Wait 5 seconds and then reconnect the device.
     

Additional considerations for iOS devices:

If you have not already done so, enable UI Automation on the device in Settings >Developer> Enable UI Automation. Disconnect the device, wait 5 seconds, and then reconnect it.

Back to top

Start and stop the connector

You can manage the connector with the following commands.

Action	Command
Start the connector	service DL start
Stop the connector	service DL stop
Restart the connector	service DL restart

Ubuntu:

• Commands to manage the connector service must be run with sudo. For example, sudo service DL start.

• Log information will print to the log file {installation path}/log/hpmc_deamon_service.log and not console output.

Back to top

Enable localization

To display system apps (apps that are used to run the device itself) in a supported language other than English, after installing the connector, navigate to /opt/UFTDigitalLab/connector/conf/connector.properties and uncomment the following line in the file:
ENABLE_LOCALIZATION=true

Back to top

Uninstall the connector

You can uninstall the connector for Linux as follows:

1. Log into the Linux connector machine as root user.

2. Change directory to the connector installation directory:
   cd <path to installation folder> (Default /opt/UFTDigitalLab/)
3. Run the uninstall script by entering the following command:
   ./DL_uninstall
   
4. Press enter to proceed with uninstalling the connector.

Back to top

Change the configuration of the connector

If you need to modify your connector details, for example to to change the server or connector details, you can use the UFT Digital Lab update tool. When you run the tool, you can update the following server or connector details:

UFT Digital Lab server details

• IP address or FQDN

• Port

• Secure or non secure connection (SSL)

• Proxy information

UFT Digital Lab Connector details

• Credentials

• Connector name

• Connector IP address

• Connector port

To change the configuration of the connector:

1. On the connector machine, log in as root or as a user in the Linux sudoers file.
2. Navigate to your connector installation directory.
   Default opt/UFTDigitalLab/
3. Run the following command:
   ./DL_update
4. When prompted, specify the new details.
   
5. Restart the connector at the end of the process to allow the change to take effect.
6. SSL access only: When you modify the connector details following a change to the server details, a new certificate is generated for the connector. Testing tool users also need to reconfigure their SSL access to Digital Lab.

Back to top

Patch installation

To benefit from the latest enhancements and fixes, install the latest patch for your current version of Digital Lab. Server and connector patches can be downloaded from Software Licenses and Downloads. The latest patch includes the content of any previous patches. There is no need to install previous patches.

When upgrading the server to the latest patch, the following should also be upgraded:

• All connectors

• Manual signing tools (if applicable)
  

  • iOS Enabler for manual signing of iOS apps. After installing the server patch, the iOS  enabler is available in the Agent folder. Patches are available on the ADM Marketplace.

  • Android Enabler for manual signing of Android apps. After installing the server patch, the updated Android enabler is available in the server folder.

Follow the patch installation instructions included in the patch release.

Back to top

See also:

• Manage devices
• SSL and certificates