Skip to content

Connecting to an Agent Machine

The Software Client for Linux can connect to any remote host with a Anyware agent installed and configured, or a Remote Workstation Card. Remote hosts can be Windows, macOS, or Linux, and connections can be made directly (client direct to host) or brokered through Anyware Manager or a Connection Manager.

Note: Remote Workstation Card connections

Connections to Remote Workstation Cards require preparation on the remote machine before they will work. For details, see Preparing for PCoIP Remote Workstation Card Connections.

Creating Your First Connection

The first step is to create a connection to either your agent (for direct connections) or to your connection manager (for managed deployments).

  1. Launch the Software Client for Linux.

  2. If this is your first connection, the Software Client for Linux will prompt you to create one:

    No previously saved connections, add a new connection

    Click Add a new connection to proceed.

  3. In the Add New Connection pane, there are two fields to provide:

    Add a new connection

    • Host Address or Registration Code: Enter the address of the remote system you want to reach (you should have this information from your system administrator). This field accepts IP addresses, domain names, and registration codes, as in these examples:

      • An IP address: 123.456.789.012
      • A domain name: remote-desktops.example.com
      • A registration code: a1b2c3!@#

      Note: Amazon WorkSpaces registration codes

      If you are connecting to an Amazon WorkSpaces desktop, provide your WorkSpaces registration code in this field.

    • Connection Name: Provide a name for this connection. This can be anything; you will use this name to select this connection in future sessions. You can always change it later.

  4. Click Add connection.

Once this is done, you'll see the connection you created shown as a clickable button. You can add as many connections as you like, by clicking + Add a new connection at the bottom of the Connect pane.

Tip: Difference from previous workflows

The connections you save here are to brokers, or to direct desktop connections. If you have multiple desktops behind a single broker, you will still have to choose your desired desktop after authenticating with the broker. In the previous interface, you could save connections at any stage of the process, including to individual desktops.

If you have existing saved connections from previous releases, they will continue to work when you upgrade to this client version. However, if they are deleted, they cannot be re-created.

Connecting to a Session

  1. Assuming you have created at least one connection, the Software Client for Linux will now look something like this:

    Example connections

  2. Click the name of the connection you want. Next, provide your username and password:

    Authenticate request

    Note: About authentication credentials

    For managed connections, the authentication screen and validation that happens here is managed by HP Anyware or by your connection broker. The credentials are supplied to you by your system administrators, and are usually your corporate credentials.

    For direct connections where no broker is present, use the credentials for your user account on the remote machine.

  3. If your system is configured for multi-factor authentication, you will see a Multi-Factor Authentication screen next. The actual view shown here depends on your MFA implementation; in this example, the MFA screen accepts a passcode or sends a push:

    MFA request

  4. Once your credentials are accepted:

    • If you have a single desktop available, your connection credentials will be used to automatically log into it and your session starts immediately.
    • If you have multiple desktops available, the Software Client for Linux shows you a list of desktops. Click the desktop you want to connect to.

      Choose a desktop

Once you are connected, your PCoIP session will begin. The connection will use the display mode you last used (windowed, fullscreen one monitor, or fullscreen all monitors), unless altered by a launch-time configuration.

There may be a delay of a few seconds before you have control of your mouse and keyboard; this is normal.

Managing Connections

  1. On the Saved connections window, click the vertical ellipsis next to the connection to reveal the context menu.

  2. To rename the connection, select Edit.

  3. Update the Host Address or Registration Code or the Connection Name as necessary.

  4. Click Save.

  5. To delete the connection, from the context menu, click Delete.

Note: More About the Manage desktops option

The Manage desktops option in the context menu is used to rename desktop labels and restart desktops in scenarios where a single desktop is associated with a connection. For more information, see Changing remote desktop labels and Restarting remote desktops.

Managing Desktops

You can manage the desktops belonging to each of your defined connections. The following actions are available, when supported by the desktop:

  • Rename the desktop's label in the client.
  • Restart the remote desktop (if supported).
  • Display information about the desktop, including its resource name and protocol.

To use these features, first display the list of desktops belonging to the connection, then select the action you want from the available desktops. These procedures are described next.

Display the List of Desktops

Desktop management options require you to authenticate with the connection that owns them.

Tip: Connections with multiple desktops

If you have multiple desktops, you can also click on a connection directly instead of following the procedure shown here. Single-desktop users are not shown a desktop list after authenticating, and must follow this procedure to manage their desktop.

To access the desktop management options:

  1. From the list of connections, click the vertical expansion icon kebab beside the connection you want to work with.
  2. From the dropwdown menu, click Manage Desktops: Manage Desktops menu You will be asked to authenticate with the connection.

Once authenticated, you will see the list of desktops belonging to the connection. To manage one of the desktops, click the vertical expansion icon kebab beside the desktop you want to work with, and choose one of the following options.

Rename a Desktop

By default, the Software Client for Linux displays the machine names of your remote desktops. These names can often be automatically-generated strings that are difficult to identify or differentiate. You can modify the name shown in the desktop list to give them human-friendly names that are easier to understand.

Note: Only labels are changed

This procedure changes the label shown in the client interface. It does not change the desktop's machine name.

To change a desktop label:

  1. Display the desktop list as described above.
  2. Click Rename:

    Rename a desktop

  3. Provide a new name to use in the desktop list. Note that once this is done, the default machine name will no longer be visible; if you need to see it later, see View Desktop Information.

Restart a Desktop

You can send a restart command to a remote desktop from the client interface, if supported by your remote system.

Note: Not all deployments support this feature

The restart option is only be available if your remote system supports it. If it does not, the option will be disabled.

To restart a remote desktop:

  1. Display the desktop list as described above.
  2. Click Restart Desktop:

    Restart a desktop

The remote desktop will be restarted. Note that it will be unavailable for connections until the restart is complete, which may take several minutes.

View Desktop Information

You can view detailed information about each of your available remote desktops, including resource names, IDs, and protocols.

Tip: Desktop machine names

If you have renamed a desktop, the original machine name is the resource name shown here.

To view desktop info:

  1. Display the desktop list as described above.
  2. Click Info:

    Get desktop info

  3. Review the displayed information.

    Desktop info menu example

  4. To dismiss the info window, click OK or click the close button in the top corner.

Some Keystrokes Will not Be Interpreted Correctly

Keystrokes of special keys sent by clients might not be interpreted correctly by agents. This happens when the clients and the agents are running different operating systems, and the special keys are unique to the operating system of the clients. For example, the Numlock keystroke sent by a Windows client does not work on a macOS agent. This is by design.

Note: Troubleshooting PCoIP Session Connection Issues

If you encounter issues with your PCoIP Session, see the following KB article: https://help.teradici.com/s/article/1027. This article details some potential causes and fixes for common connection issues.

Using Smart Card Authentication to Connect to a Session

Anyware Linux Client supports smart card authentication, provided that:

  • The client connects to a Windows Graphics Agent or a Windows Standard Agent, and

  • The client machine as well as the agent machine are running version 24.03 or later.

Additionally, you must use a combination of supported smart cards and readers in your deployment.

Note: Concurrent Users Cannot Logon

Concurrent users cannot log on to agent machines using the same smart card for authentication. Smart cards having multiple certificates allow only one user to log on at a time. to be able to log in, others users must wait until the current users logs off.

To use a smart card for authentication:

  1. Attach the smart card reader to the Anyware Linux Client.

  2. Launch the Software Client for Linux.

  3. On the Saved Connections window, select a connection.

    List of Connections

  4. When the Smart Card Verification window appears, insert your smart card and wait until it is verified.

    Insert Smart Card

  5. Do one of the following:

    • If the client detects only one certificate, provide the smart card PIN and click Connect on the Smart Card Verification window.

      Single Certificate

    • If the client detects multiple certificates, on the Smart Card Verification window, select a certificate, provide the smart card PIN, and click Connect.

      Multiple Certificates

  6. On the Desktop Selection window, select a desktop and connect to this session.

Note: Removing the Smart Card During Session

Removing the smart card while in session will end the session. However, the smart card will continue to be available on the client machine.

Viewing Certificate Information

You can view detailed information about each of the certificates detected by the client, such as certificate authority, certificate recipient, certification path, and certificate properties.

To view certificate information:

  1. Launch the client, slect a connection, and insert your smart card. Wait until it is verified.

  2. From the available certificates, select one for which you want to view details.

Information related to the certificate is displayed on the Certificate details window under the following tabs:

  • General: Contains general information such as certifying authority, validity, and certificate recipient.

  • Details: Contains details about the properties of the certificate such as key usage, thumbprint, and subject alternative name.

  • Certification Path: Contains information about the certification path of the certificate.