Teradici PCoIP Software Client for Mac

Teradici PCoIP Software Client for Mac Version 3.3 Administrators' Guide TER1706003-3.3

Contents Who Should Read This Guide? 4 Welcome to PCoIP Software Client for Mac 5 What's New in This Release? 5 Additional Documentation 5 System Requirements 7 Client Platforms 7 Virtual Host Platforms 7 Remote Workstation Platforms 7 Remote Workstation Configuration Requirements 8 Disabling Temporal Dithering 8 Configuring PCoIP Host Software to Start Automatically (Linux Workstations) 8 Installing or Uninstalling PCoIP Software Clients 9 Before You Begin 9 Installing and Uninstalling PCoIP Software Client for Mac 9 Installing the PCoIP Software Client for Mac 9 Uninstalling the PCoIP Software Client for Mac 10 Using the PCoIP Software Client 11 Connecting to a Remote Workstation or Virtual Desktop 11 Connecting to a Teradici PCoIP Remote Workstation Card 15 Connecting to a USB Device 16 Connecting to Human Interface Devices (HIDs) 18 Using Saved Connections 19 Changing the PCoIP Software Client Window Mode 21 Displaying the Utility Menu Bar 22 Switching between Fullscreen One Monitor and Fullscreen All Monitors 22 Minimizing the Client from Full-Screen Mode 23 Sending a Ctrl-Alt-Del Command 24 Changing the Language 24 Checking the PCoIP Software Client Software Release 25 Disconnecting a Session 26 Quitting the Teradici PCoIP Client Application 26 Troubleshooting Your PCoIP Software Client 27 Session Log IDs 27 Setting Log Levels 27 Locating PCoIP Software Client for Mac Log Files 28 TER1706003 2

PCoIP Software Client Security Modes 29 Changing the Default Security Mode in Mac 29 Getting Support 30 Contacting Support 30 The Teradici Community Forum 31 TER1706003 3

Who Should Read This Guide? This guide is intended for administrators who are responsible for installing and setting up Teradici PCoIP Software Client for Mac to connect to any of the following products: Teradici Cloud Access Software Teradici PCoIP Remote Workstation Card installed in a physical remote workstation Note: Understanding terms and conventions in Teradici guides For information on the industry specific terms, abbreviations, text conventions, and graphic symbols used in this guide, see Using Teradici Product and Component Guides and the Teradici Glossary. TER1706003 4

Welcome to PCoIP Software Client for Mac Welcome to the Teradici PCoIP Software Client for Mac Administrators' Guide. PCoIP Software Clients are applications for Windows, Mac, and Linux computers that enable users to establish PCoIP sessions with remote workstations and desktops. This guide explains how to install, configure, and use these software clients for Mac operating system. It includes details about the system requirements for client and remote workstation platforms, and where you can find the PCoIP Software Client log files. What's New in This Release? Release 3.3 of the PCoIP Software Client for Mac includes the following features: Enhanced audio and video synchronization (Technology Preview) Improved full-screen video playback, reducing the difference in delays between the audio and video channels. Improved lip sync for movie playback. This feature is currently a technology preview and disabled by default. To enable the feature, execute the following command to set the feature in the com.teradici.teradici PCoIP Client.plist file and reconnect the session: defaults write "com.teradici.teradici PCoIP Client.plist" enable_ enhanced_avsync 1 To disable the feature: defaults delete "com.teradici.teradici PCoIP Client.plist" enable_ enhanced_avsync Additional Documentation The following guides contain additional information on PCoIP Software Clients: For a summary of feature additions, important bug fixes, and known issues, see: o Teradici PCoIP Software Client 3.3.0 for Mac Release Notes TER1706003 5

For more information about Teradici Cloud Access Software, including detailed information on included PCoIP components as well as Teradici All Access plans, see the following guides: o Teradici Cloud Access Architecture Guide For information about the Teradici PCoIP Host Software that is required on remote workstations with a Teradici PCoIP Remote Workstation Card installed, see the following guides: o o PCoIP Host Software for Windows User Guide PCoIP Host Software for Linux User Guide TER1706003 6

System Requirements In this section, you'll learn about the client, virtual host, and remote workstation platforms that support your PCoIP Software Client. Client Platforms PCoIP Software Client for Mac is supported on the following client platforms: macos Sierra (10.12) Mac OS X El Capitan (10.11) Virtual Host Platforms PCoIP Software Clients can connect to virtual desktops with a PCoIP agent installed as part of the Teradici Cloud Access Software. For details on this Teradici Cloud Access, including supported host operating systems and links to PCoIP agent documentation, see: Teradici Cloud Access Architecture Guide Teradici PCoIP Graphics Agent 2.10 for Windows Administrators' Guide Teradici PCoIP Standard Agent 2.10 for Windows Administrators' Guide Teradici PCoIP Graphics Agent 2.10 for Linux Administrators' Guide Teradici PCoIP Standard Agent 2.10 for Linux Administrators' Guide Remote Workstation Platforms PCoIP Software Clients can connect to the Teradici PCoIP Remote Workstation Card. Supported Teradici PCoIP Remote Workstation Cards: TERA22x0 with firmware 4.9 or later Teradici PCoIP Host Software must be installed on the workstation. The following software versions are supported in this release: PCoIP Host Software for Windows: 4.2.2 or later PCoIP Host Software for Linux: 4.7.0 or later TER1706003 7

Caution: Enable monitor emulation To prevent a gray screen when you connect, you must enable monitor emulation for the video ports on your remote workstation. To configure, log in to the card s Administrator Web Interface (AWI) and select Enable Monitor Emulation on Video Port n from the Configuration > Monitor Emulation menu. For more information, see the Tera2 PCoIP Zero Client Firmware 4.x and Remote Workstation Card Firmware 4.9 Administrators' Guide. Remote Workstation Configuration Requirements Before using a PCoIP Software Client to connect to a remote workstation, ensure that the workstation is configured as outlined next. Disabling Temporal Dithering Temporal dithering causes blurriness, heavy packet loss, and high CPU usage on the PC running the client during a PCoIP session. If the graphics card (GPU) on the remote workstation supports temporal dithering, this feature must be disabled before establishing a PCoIP session. The Windows NVIDIA driver does not enable temporal dithering by default, but most AMD drivers do. For more information, see Should I disable the dithering feature of my graphics card in a remote workstation environment? (KB 15134-207). Configuring PCoIP Host Software to Start Automatically (Linux Workstations) To avoid mouse and keyboard issues, administrators must configure each Linux workstation to automatically start up the PCoIP Host Software for Linux when a user logs in. To configure PCoIP host software to start automatically: 1. Log in to the Linux workstation using either a zero client or mouse and keyboard that are directly connected to the workstation. 2. Modify the workstation startup script to launch the PCoIP host software automatically. For details, see Installing PCoIP Host Software Binary RPM in the PCoIP Host Software for Linux User Guide. TER1706003 8

Installing or Uninstalling PCoIP Software Clients In this section, you'll learn how to install and uninstall PCoIP Software Client for Mac. Before You Begin Before installing a PCoIP Software Client: Log in as an administrator to the local machine on which you want to install the program. The installation requires administrator privileges. Ensure that any previously installed PCoIP Software Client application is closed prior to installing the new client. Installing and Uninstalling PCoIP Software Client for Mac This topic describes how to install and uninstall the PCoIP Software Client for Mac. Note: Reinstalling or installing a previous version of the PCoIP Software Client for Mac You do not need to manually uninstall the PCoIP Software Client for Mac to install a different version. When you drag the PCoIPClient file to the Applications folder, the system will ask to replace the older version. If you agree to replace, the older version is automatically deleted. Alternatively, you can keep both versions, in which case the new version is given a different name. Installing the PCoIP Software Client for Mac Use the following procedure to install the PCoIP Software Client for Mac. To install the PCoIP Software Client for Mac: 1. Copy the PCoIP Software Client disk image file (PCoIPClient.dmg) to your Mac desktop. 2. Double-click the file to mount the volume. TER1706003 9

3. Accept the license agreement by clicking Agree. 4. In the PCoIPClient volume window, drag the PCoIPClient icon into the Applications folder icon to install the program. 5. If desired, you can also create an alias from this window: a. Double-click the Applications folder icon to open the folder. b. Drag the PCoIPClient application to the desktop or Dock. 6. To eject the volume when you are finished, drag it to the trash. Uninstalling the PCoIP Software Client for Mac Use the following procedure to uninstall the PCoIP Software Client for Mac. To uninstall the PCoIP Software Client for Mac: Navigate to the Applications folder and drag the PCoIPClient program to the trash. Or, right-click the application and select Move to Trash. TER1706003 10

Using the PCoIP Software Client After installing a PCoIP Software Client on your client machine, you can connect to the following PCoIP solutions or products or hosts: Teradici PCoIP Graphics Agent or PCoIP Standard Agent installed as part of Teradici Cloud Access Software. Teradici PCoIP Remote Workstation Card and Teradici PCoIP Host Software installed in a Windows or Linux workstation. You can configure your PCoIP Software Client to perform specific tasks, including: Connecting to a Remote Workstation or Virtual Desktop on page 11 Connecting to a Teradici PCoIP Remote Workstation Card on page 15 Connecting to a USB Device on page 16 Connecting to Human Interface Devices (HIDs) on page 18 Using Saved Connections on page 19 Changing the PCoIP Software Client Window Mode on page 21 Sending a Ctrl-Alt-Del Command on page 24 Changing the Language on page 24 Checking the PCoIP Software Client Software Release on page 25 Disconnecting a Session on page 26 Quitting the Teradici PCoIP Client Application on page 26 Connecting to a Remote Workstation or Virtual Desktop You can access a remote workstation or a virtual desktop with the PCoIP Graphics Agent or PCoIP Standard Agent installed. To access a remote workstation or virtual desktop: 1. Double-click the PCoIP Client desktop icon, alias, or program file (pcoip_ client.exe for Windows or PCoIPClient for Mac) to launch the application. 2. In the Host Address box, enter the fully-qualified computer name or IP address of your remote workstation or virtual desktop. TER1706003 11

Optional: In the Connection Name box, enter a name for your connection. This field accepts any Unicode character. Note: The connection information can be saved If you provide a connection name now, you will have the option to save the connection after you are authenticated. Saved connections can be quickly recalled later, without manually re-entering connection information. Caution: Leave PCoIP Remote Workstation card checkbox unchecked Do not enable the Connect to PCoIP Remote Workstation card option. 3. Click NEXT. TER1706003 12

4. At the next screen, select your domain from the list, enter your user name and password for the workstation or desktop, and then click LOGIN. If your domain does not display in the list, specify it along with your user name (for example, MyDomain\MyUserName). The login screen displays a red padlock icon when accessing a PCoIP agent desktop that uses the default self-signed certificates. This icon indicates that the software s certificate is not signed by a trusted certificate authority (CA). You can use your own internal CA to create a certificate and then install the appropriate files at each end. If the client trusts your internal CA, a green padlock icon displays on the screen instead. To learn more about certificates, see the PCoIP agent administrators guides listed in the Teradici Cloud Access Architecture Guide. TER1706003 13

5. If your login is successful, the following screen appears. Select your preferred view (WINDOWED or FULL-SCREEN), click the desktop you will connect to, and then click one of the following: To immediately connect, click CONNECT. To save your connection information, click SAVE. The SAVE button only appears if you provided a name in step 3. Note: A short interface delay is normal When a session is first connected, it may take a few seconds before you can take control of the keyboard and mouse. This is normal behavior. 6. If your system is locked after connecting, choose Connection > Send CTRL- ALT-DEL from the client menu and enter your login credentials. TER1706003 14

Connecting to a Teradici PCoIP Remote Workstation Card You can access a remote workstation with a Teradici PCoIP Remote Workstation Card installed. To access a remote workstation with a Teradici PCoIP Remote Workstation Card installed: 1. Double-click the PCoIP Client desktop icon, alias, or program file (PCoIPClient) to launch the application. 2. In the Host Address box, enter the fully-qualified computer name or IP address of the Teradici PCoIP Remote Workstation Card installed in the remote workstation. 3. Optional: In the Connection Name box, enter a name for your connection. This field accepts any Unicode character. Note: The connection information can be saved If you provide a connection name now, you will have the option of saving the connection after you are authenticated. Saved connections can be quickly recalled later, without manually re-entering connection information. 4. Enable the Connect to PCoIP Remote Workstation card option. TER1706003 15

5. Click CONNECT. Note: A short interface delay is normal When a session is first connected, it may take a few seconds before you can take control of the keyboard and mouse. This is normal behavior. 6. If your system is locked upon connection, select the Connection > Send CTRL- ALT-DEL menu from the PCoIP Software Client to log in, and then enter your user name and password. Connecting to a USB Device These instructions apply only to systems using the Teradici PCoIP Standard Agent for Windows or Teradici PCoIP Graphics Agent for Windows. USB must be enabled on the host for the client to connect to a USB device. Note: USB devices cannot be simultaneously accessed by hosts and clients When you make a USB device available to your remote host, it is disabled on your client s computer. Note: One-time PCoIP Software Client for Mac login The first time you connect after a Mac installation, you must enter a Mac administrator user name and password. You only need to do this once. To connect to a USB device: 1. Ensure the USB device is attached. 2. Select the Connection > USB Devices menu option. TER1706003 16

3. Click Connect beside the USB device you want. Note: About the USB device list Many systems have integrated USB devices, such as webcams on laptops, that always appear in this list in addition to devices you have plugged in yourself. Some devices will identify themselves only as USB Device. To disconnect a USB device: 1. Select the Connection > USB Devices menu option. TER1706003 17

2. Click Disconnect beside the USB device you want to disconnect. Connecting to Human Interface Devices (HIDs) Human Interface Devices, or HIDs, are the devices you use to interact with your desktop. Keyboards, mice, and tablets are all examples of HIDs. Most HIDs are terminated locally, meaning the PCoIP client handles their input and sends it to the PCoIP host. Locally terminated HIDs do not require any special configuration to work. Some HIDs, such as Wacom tablets or 3D mice, cannot be locally terminated and must be passed through to the host for handling through a process called bridging. To enable HID bridging on the client machine, navigate to Connection > USB Devices and enable the HID checkbox, as shown next. TER1706003 18

Caution: Bridging also requires host configuration Before bridged devices will work on the host, you must configure the host PCoIP agent. For detailed information, see the administrators guide for your desktop s agent: Teradici PCoIP Graphics Agent 2.10 for Windows Administrators' Guide Teradici PCoIP Standard Agent 2.10 for Windows Administrators' Guide Teradici PCoIP Graphics Agent 2.10 for Linux Administrators' Guide Teradici PCoIP Standard Agent 2.10 for Linux Administrators' Guide Using Saved Connections Once you have saved a connection, you can use it to reconnect easily. To reconnect using your saved connection: TER1706003 19

1. Click the button for the saved connection. The button label displays the connection name you assigned when you configured the connection. 2. To see the connection address, hover your mouse over the saved connection. Hovering over a saved virtual desktop will also show the desktop name. 3. To edit or delete a saved connection, click the configure button on the right, and then select the desired option from the popup menu. TER1706003 20

4. If you have saved multiple connections, click the desired one to reconnect. If you have more than four saved connections, additional saved connection buttons appear in an extended area of the page. Use the forward and back arrows to navigate between areas. 5. Any time you wish to connect to a new workstation, just click NEW CONNECTION to return to the main screen, and then enter the connection details. Changing the PCoIP Software Client Window Mode You can display the PCoIP Software Client window in full-screen or windowed mode. Full-screen is the recommended mode to use for best results. From either client, select View > Show/Hide Fullscreen All Monitors or Show/Hide Fullscreen One Monitor to change the screen mode. You can also toggle between windowed and full-screen modes using the following key sequences: Show Fullscreen One Monitor: Ctrl+Option+Return TER1706003 21

Note: Identical hotkey for Show Fullscreen All Monitors and Show Fullscreen One Monitor The hotkey sequence for Show Fullscreen All Monitors and Show Fullscreen One Monitor is identical. This is because the hotkey is a toggle between these two modes. You need to use the menu item to switch between all monitors or one monitor, then you can use Ctrl+Option+Return to toggle between fullscreen and windowed mode. See Switching between Fullscreen One Monitor and Fullscreen All Monitors on page 22. Note: Maximizing window does not equal full-screen mode Maximizing the window does not put the PCoIP Software Client window into full-screen mode. Displaying the Utility Menu Bar In full-screen mode, PCoIP Software Client menus are located in a drop-down utility menu bar. You can display this menu bar by moving the mouse cursor to the top of the screen. Switching between Fullscreen One Monitor and Fullscreen All Monitors You can change directly from Fullscreen All Monitors to Fullscreen One Monitor and back using the View menu: TER1706003 22

Minimizing the Client from Full-Screen Mode You can minimize the PCoIP Software Client while in full-screen mode by navigating to View > Minimize Client: You can also minimize the client by using the following key sequence: Ctrl+Option+M TER1706003 23

Sending a Ctrl-Alt-Del Command To send the Ctrl-Alt-Del keyboard command to a remote workstation, select the Connection > Send CTRL-ALT-DEL menu option. Changing the Language In addition to English, the PCoIP Software Client also supports these languages: Chinese (Simplified), French, German, Italian, Japanese, Korean, Portuguese (Brazil), Portuguese (Europe), Russian, Spanish, and Turkish. During installation, you can select one of the supported languages. To change the language after installation: In System Preferences > Language & Region > Advanced > General tab, select another language in the Format language list. TER1706003 24

Checking the PCoIP Software Client Software Release The PCoIP Software Client pre-session window contains an About button in the lower left of the window. Click this button and then select About from the popup menu to display the PCoIP Software Client software release version. From either client, you can also select the Teradici PCoIP Client > About Teradici PCoIP Client menu to display the software release version from within a PCoIP session. TER1706003 25

Note: About menu item only appears when the client is in session The About Teradici PCoIP Client menu item only appears when the client is in session. The menu item is not available from the pre-session GUI. Disconnecting a Session To disconnect a PCoIP session from either client, but still leave the PCoIP Software Client application running, select the Connection > Disconnect menu option. Tip: Quickly disconnect from a session To quickly disconnect from a session, press Ctrl+Option+F12. Quitting the Teradici PCoIP Client Application To disconnect a PCoIP session and quit the application at the same time: Select the Teradici PCoIP Client > Quit Teradici PCoIP Client menu option. Or, you can simply press Command+Q. TER1706003 26

Troubleshooting Your PCoIP Software Client This section demonstrates using PCoIP Software Client log files to troubleshoot problems you may encounter with your PCoIP Software Client. PCoIP Software Client logs are text (.txt) files that contain system and session information about your connection. They are useful for troubleshooting problems. A new log file is created each time you use a PCoIP Software Client to initiate a PCoIP session. If you experience a problem, recreate the issue, then send your most recent PCoIP Software Client log file along with any relevant screenshots to Teradici Support, as per your support agreement. You can also check the Teradici PCoIP Community Forum for troubleshooting information about this product. Session Log IDs The PCoIP Software Client creates a unique session ID when a new session is established, and distributes that ID to all components in the system. When PCoIP components generate log messages, they are prefixed by this unique session ID, allowing administrators and support to easily group events by session across multiple components: yyyy-mm-ddthh:mm:ss.ffffffz xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx > For example: 2015-11-06T08:01:18.688879Z 4208fb66-e22a-11d1-a7d7-00a0c982c00d > Log messages that do not pertain to a specific session will show a string of zeroes in place of the session log ID number. Setting Log Levels You can set log levels to determine the level of details provided in the log. Log levels range from 0 to 3, where 0 provides the least information and 3 provides the most information. To set log levels on Mac, enter the following command: open /Applications/PCoIPClient.app --args -l x where l is lowercase L and x is desired the log level (1, 2, or 3). TER1706003 27

Locating PCoIP Software Client for Mac Log Files On a Mac computer, PCoIP Software Client log files are located within the user s Home Library folder, which is hidden by default. The recommended way to access Home Library files is to use the macos Console. You can also display log files in a macos terminal window. To display log files using the macos Console: 1. To open the Console, go to the Applications > Utilities folder, and then doubleclick Console. 2. In the FILES section of the Log List pane on the left, navigate to the following folder: ~/Library/Logs/Teradici/PCoIPClient 3. Select the desired log file to view its contents in the main pane. 4. To copy the contents: a. Click anywhere in the log contents, and then select Edit > Select All. b. Select Edit > Copy. c. Paste the contents into an email or text file. To display log files in a macos terminal window: 1. To open a terminal window, go to the Applications > Utilities folder, and then double-click Terminal. 2. Navigate to the PCoIP Software Client log folder by typing the following command at the command line prompt: cd ~/Library/Logs/Teradici/PCoIPClient 3. Type ls to display the list of log files. 4. To view the contents of a log file, use any macos command-line editor to open it. 1. To open a terminal window, go to the Applications > Utilities folder, and then double-click Terminal. 2. Navigate to the PCoIP Software Client log folder by typing the following command at the command line prompt: cd ~/Library/Logs/Teradici/PCoIPClient 3. Type ls to display the list of log files. 4. To view the contents of a log file, use any macos command-line editor to open it. TER1706003 28

PCoIP Software Client Security Modes The PCoIP Software Client uses certificates to verify the identity of the host to which it connects. The security mode is configured by the security_mode= setting in the Teradici PCoIP Client configuration file, which is described next. Three security mode options are available: security_mode=0 (verification is not required) A red, unlocked padlock icon appears on the client login screen. security_mode=1 (warn but allow) This is the default mode in this release. If a certificate cannot be verified, an 'untrusted server' warning displays and a red, unlocked padlock icon appears on the client login screen. Users still have the option of connecting. security_mode=2 (full verification is required) Users cannot connect unless a certificate can be verified. Note: PCoIP sessions are always encrypted Your PCoIP session is still encrypted and secure if you connect with security mode 0 or 1. The red padlock icon indicates that the certificate presented by the host is not signed by a trusted certificate authority in the client s certificate store, not that the session is insecure. Changing the Default Security Mode in Mac For Mac, the security mode option is stored in a property list file called /users/<user_name>/library/preferences/com.teradici.teradici PCoIP Client.plist To change the default security mode: 1. Close the PCoIP Software Client. 2. Open a terminal window and type the following command at the command line: defaults write com.teradici.teradici PCoIP Client security_mode <value> where <value> is your desired security option (0, 1, or 2). TER1706003 29

Getting Support If you are having trouble, help is always available. This section contains information about contacting Teradici support and connecting with the Teradici user community. Contacting Support If you encounter problems installing or using Teradici technology, you can: Check for updated release notes, which may address the issue you are experiencing. Release notes are published on Teradici Support. Browse the Teradici Knowledge Base. Submit a support ticket. TER1706003 30

The Teradici Community Forum The PCoIP Community Forum allows users to have conversations with other IT professionals to learn how they resolved issues, find answers to common questions, have peer group discussions on various topics, and access the Teradici PCoIP Technical Support Service team. Teradici staff are heavily involved in the forums. To join the Teradici community, visit the Teradici Community Forum. TER1706003 31

Teradici Corporation #101-4621 Canada Way, Burnaby, BC V5G 4X8 Canada phone +1.604.451.5800 fax +1.604.451.5818 www.teradici.com The information contained in this documentation represents the current view of Teradici Corporation as of the date of publication. Because Teradici must respond to changing market conditions, it should not be interpreted to be a commitment on the part of Teradici, and Teradici cannot guarantee the accuracy of any information presented after the date of publication. This document is for informational purposes only. TERADICI MAKES NO WARRANTIES, EXPRESS, IMPLIED OR STATUTORY, AS TO THE INFORMATION IN THIS DOCUMENT. Complying with all applicable copyright laws is the responsibility of the user. Without limiting the rights under copyright, no part of this document may be reproduced, stored in or introduced into a retrieval system, or transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or otherwise), or for any purpose, without the express written permission of Teradici Corporation. Teradici may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this document. Except as expressly provided in any written license agreement from Teradici, the furnishing of this document does not give you any license to these patents, trademarks, copyrights, or other intellectual property. Visit Notice of Intellectual Property Rights for more information. 2004-2017 Teradici Corporation. All rights reserved. Teradici, PC-over-IP, and PCoIP are trademarks of Teradici Corporation and may be registered in the United States and/or other countries. Any other trademarks or registered trademarks mentioned in this release are the intellectual property of their respective owners. TER1706003 32