Configuring the Anyware Software Client (2024)

The Software Client for macOS provides a number of configurable settings and behaviors, which allow the setting of user options, performance modes, and triggering actions like automated connections. These settings are not persistent and cannot be set via the user interface; they are set by launching the application using one of the methods described next.

To configure a client instance, you must launch it using one of these methods:

  • On the command line, with configuration values passed inline as flags
  • Via a URI, providing your configuration values in an encoded JWT string
  • via Config files, where advanced configuration values are set via configuration files

Note: Configuration Methods

Not all options available via the configuration methods are the same. Some might also have different names.

Setting Configuration Values on the Command Line

To set configuration values this way, launch the Software Client for macOS from a command prompt, and include the required options as flags. Multiple flags can be included in the same line. Use the following conventions when setting these parameters:

TypeFormat
BooleanNo value is required; the flag implies "True"
NumericProvide the parameter and then the numeric value, separated by a space.
StringProvide the parameter and then the string value, separated by a space.
Values can be wrapped in double quotation marks if they contain spaces.

The following example launches the client in full-screen mode, sets log level 3, and points to a connection broker at broker.domain.com (if your application is installed somewhere else, use your own path instead):

/Applications/PCoIPClient.app/Contents/MacOS/PCoIPClient --connection-broker broker.domain.com --log-level 3 --full-screen

The available settings are shown below.

Setting Configuration Values via a URI

Using this method, the Software Client for macOS is launched using a URI with configuration options (and, optionally, connection credentials) encoded in a JWT token string.

To use this method, create a URI with the following structure:

pcoip://[broker]/connect[?data={jwt}]

Where each segment shown above is:

SegmentDescription
pcoip://Required. This scheme is registered with the operating system and will launch the Software Client for macOS.
brokerOptional. FQDN of the connection broker to use. If the connection is not brokered, this can be omitted.
/connectRequired. Requests a connection with the parameters defined in "?data"
?data={jwt}Optional. The string indicated by {jwt} here is a JWT payload, containing any required configuration settings and connection credentials. If all you want to do is launch the client with no options set, this can be omitted.

The JWT payload can contain both credential information and client configuration. To create the JWT payload:

  1. Create your configuration and credentials as a JSON object, using available configuration parameters and authentication credentials.
  2. Encode the object as a JWT token.
  3. Pass the token through the URI as the data parameter.

For example, the following JSON object would launch the client in full-screen mode, with log level 3:

{ "fullscreen":true, "log-level":3}

Encoded, and pointing to a connection broker at broker.domain.com, this would result in a URI similar to the following:

pcoip://broker.domain.com/connect?data=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJmdWxsc2NyZWVuIjp0cnVlLCJsb2ctbGV2ZWwiOjN9.3MRUQ4VeKHbCnkG4OIXsUYp2N1IGf6AzTIo8tnFoXoA

The available settings are shown below.

Configurable Settings

The following settings can be configured on the Software Client for macOS.

General Settings

These settings affect the client's behavior both in and out of PCoIP sessions.

Language

Sets the user interface language.

OptionsDefaultType
Interface languageEnglishstring (short code or ISO code; see next table for options)

Supported language options:

LanguageShort codeISO code
Chinese Simplifiedcnzh_CN
Englishenen_US
Frenchfrfr_FR
Germandede_DE
Italianitit_IT
Japanesejaja_JP
Koreankoko_KR
Portuguese (Iberian)ptpt_PT
Spanisheses_ES

Usage

MethodValidFullAliasExample
Command Line--locale--locale zh_CN
URI

If the locale parameter is present but the argument is invalid or missing, the Software Client for macOS displays a Parameter parsing error and lists the valid settings, then exits (the client will not start).

Connection Settings

These settings control how the Software Client for macOS connects to PCoIP sessions.

Connection Broker

The connection broker's URL.

Note that this parameter is used by the command line only; when using the URI method, the connection broker URL is part of the URI (not part of the configuration JWT payload).

ValuesDefaultType
The URL for the connection broker, if presentstring

Usage

MethodValidFullAliasExample
Command Line--connection-broker-b -b broker.domain.com
URI

Desktop

The name of the desktop to connect to.

ValuesDefaultType
The name of a desktop to conect tostring

Usage

MethodValidFullAliasExample
Command Line--desktop--desktop myDesktop
URIdesktopvm{vm: "myDesktop"}

Domain

The domain to send to the connection broker.

OptionsDefaultType
The name of the domain to provide to the connection broker.string

Usage

MethodValidFullAliasExample
Command Line--domain-d--domain domain.example.com
URIdomaindom{dom: "domain.example.com"}

Hard Host

If connecting to a Remote Workstation Card (also known as a hard host), provide its URL using this parameter.

This option is ignored if the connection-broker url is provided.

OptionsDefaultType
The URL for the Remote Workstation Card.string

Usage

MethodValidFullAliasExample
Command Line--hard-host-h-h rwc.example.com
URI

Password

The password sent to the Connection Broker, for logging into a desktop. Transmitting passwords this way is not recommended.

Note: Command-line only

Passwords can only be sent via the command line. You cannot send a password in a JWT payload.

OptionsDefaultType
A string password.Not setstring

Usage

MethodValidFullAliasExample
Command Line--password-p-p mypassword
URI

Session ID

This setting launches the JSESSIONID. This parameter is only available via JWT; it cannot be used on the command line.

OptionsDefaultType
The session ID to launch.Not setboolean

Usage

MethodValidFullAliasExample
Command Line
URIsessionidsid{sid: exampleSessionID}

Username

The username sent to the Connection Broker.

OptionsDefaultType
The username to pass to the connection brokerNot setstring

Usage

MethodValidFullAliasExample
Command Line--username-u-u myUsername
URIusernameusr{usr: "myUsername"}

USB Settings

These settings control how USB devices connect to PCoIP sessions, including rules for which devices are allowed to be forwarded.

Disable USB

USB devices are available by default. Use this flag to disable USB connections. This will not prevent simple human input devices like mice or keyboards from connecting.

OptionsDefaultType
true: disabled
false: enabled
false (USB enabled)boolean

Usage

MethodValidFullAliasExample
Command Line--disable-usb--disable-usb
URIdisable-usbnousb{nousb: true}

USB Auto-Forward

This setting auto-forwards all non-HID devices to the host.

OptionsDefaultType
True: Auto-forward USB devices
False: Do not auto-forward USB devices
False (do not auto-forward)boolean

Usage

MethodValidFullAliasExample
Command Line--usb-auto-forward--usb-auto-forward
URIusb-auto-forwarduaf{uaf: true}

Note: This setting is available in the user interface

This setting is also available in the client's pre-session user interface, by clicking the gear icon and selecting USB Devices.

Vidpid Auto-Forward

To auto-forward specific devices, provide their VID and PID values separated by a comma (,). Multiple values can be provided, separated by spaces. Enclose the list in quotation marks.

OptionsDefaultType
The list of VID,PID values to auto-forwardNot setstring

Usage

MethodValidFullAliasExample
Command Line--vidpid-auto-forward--vidpid-auto-forward "aa11,bb22 cc33,dd44"
URIvidpid-auto-forwardvaf{vaf: "aa11,bb22 cc33,dd44"}

If you are not sure of the device's ID values, see Identifying Vendor and Product IDs for instructions.

Vidpid Black List

To block specific devices from auto-forwarding at all, provide their VID,PID values as a space-separated list using this parameter.

This setting overrides usb-auto-forward and the USB dialog in the client interface.

OptionsDefaultType
The list of VID,PID values to blockNot setstring

Usage

MethodValidFullAliasExample
Command Line--vidpid-black-list--vidpid-black-list "aa11,bb22 cc33,dd44"
URIvidpid-black-listvbl{vbl: "aa11,bb22 cc33,dd44"}

If you are not sure of the device's ID values, see Identifying Vendor and Product IDs for instructions.

Session Behavior Settings

These settings control the client's behavior once a session is connected.

Fullscreen Mode

Fullscreen mode enables the display topology to support multiple monitors as an extended desktop.

If both fullscreen and windowed parameters are sent, the client will launch in Windowed mode.

OptionsDefaultType
true: full screen
false: windowed
Not set (uses client's last-set mode)boolean

Usage

MethodValidFullAliasExample
Command Line--fullscreen-f-f
URIfullscreenfull{full: true}

Windowed Mode

Launches the client in windowed mode.

If both fullscreen and windowed parameters are sent, the client will launch in Windowed mode.

OptionsDefaultType
True: Launch in windowed mode
False: Do not request windowed mode
False (does not request windowed mode)boolean

Usage

MethodValidFullAliasExample
Command Line--windowed-w-w
URIwindowedwin{win: true}

Log Settings

These settings control logging functionality, including verbosity and file location.

Log Folder

A custom location for client log files.

OptionsDefaultType
A valid system path to a folderNot setstring

Usage

MethodValidFullAliasExample
Command Line--log-folder--log-folder path/to/folder
URI

Log ID

A unique ID that will identify sessions in all PCoIP log files (including those created by other components like agents and a connection manager).

OptionsDefaultType
A unique session identifierNot setstring

Usage

MethodValidFullAliasExample
Command Line--log-id--log-id abcde1234
URI

Log Level

Sets the log level. This parameter will override any existing configuration values.

OptionsDefaultType
0: Critical
1: Error
2: Info
3: Debug
4: Verbose
Not setinteger

Usage

MethodValidFullAliasExample
Command Line--log-level-l-l 2
URIlog-levellogl{logl:2}

Note: This setting is available in the user interface

This setting is also available in the client's pre-session user interface, by clicking the gear icon and selecting Logs.

Log Prefix

A user-defined prefix for log files. This value will be prepended to the timestamp in the log file name, like this:

<log-prefix value><timestamp>

Log files are saved in the location provided by log-folder.

OptionsDefaultType
A prefix to use in generated log file namesNot setstring

Usage

MethodValidFullAliasExample
Command Line--log-prefix--log-prefix example-prefix
URI

Advanced Settings

Caution: General use of these settings is not recommended

These settings are intended for specific use cases, and can drastically alter the behavior of the Software Client for macOS. Unless you understand what these settings do, and have a clear need to use them, they should be avoided.

Disable Hotkeys

Session convenience hot keys, such as Ctrl+Delete+F12 (which disconnects a PCoIP session) are available to users by default. Use this flag to disable all hotkeys.

OptionsDefaultType
true: disabled
false: enabled
false (hotkeys enabled)boolean

Usage

MethodValidFullAliasExample
Command Line--disable-hotkeys--disable-hotkeys
URIdisable-hotkeysnohot{nohot: true}

Disable Menu Bar

The Anyware client menu bar is available to users by default. Use this flag to disable the menu bar, preventing users from accessing it or executing any of its functionality.

OptionsDefaultType
true: disabled
false: enabled
false (menu bar enabled)boolean

Usage

MethodValidFullAliasExample
Command Line--disable-menubar--disable-menubar
URIdisable-menubarnomenu{nomenu: true}

Enable Scaling

This setting enables scaling on the Anyware Client without having to specify the desktop resolution. This can only be configured on a single display. This is off by default.

OptionsDefaultType
true: scaling enabled
false: scaling disabled
false (scaling disabled)boolean

Usage

MethodValidFullAliasExample
Command Line--enable-scaling--enable-scaling
URIenable-scalingscale{scale: true}

Force Native Resolution

This setting sets the resolution of the Client monitor to the native resolution when the session client is launched. This can only be configured on a single display.

Note: Windows client only

This parameter is only available on Windows clients. It will have no effect if provided to a Linux or macOS client.

OptionsDefaultType
true: force enabled
false: force disabled
false (Resolution force disabled)boolean

Usage

MethodValidFullAliasExample
Command Line--force-native-resolution--force-native-resolution
URIforce-native-resolutionnative{native: true}

Maintain Aspect Ratio

This setting maintains the display aspect ratio between the host and the Client. Maintaining the aspect ratio in this way can result in letterboxing if the two devices are naturally different.

This can only be configured on a single display.

OptionsDefaultType
true: Maintain aspect ratio
false: Do not maintain aspect ratio
False (does not maintain aspect ratio)boolean

Usage

MethodValidFullAliasExample
Command Line--maintan-aspect-ratio--maintain-aspect-ratio
URImaintain-aspect-ratioaspect{aspect: true}

Quit After Disconnect

If this is enabled, disconnecting from the PCoIP session will immediately quit the Software Client for macOS.The pre-session interface will not be available after disconnecting.

OptionsDefaultType
True: Quit on disconnect
False: Do not quit, show pre-session UI on disconnect
False (does not quit on disconnect)string

Usage

MethodValidFullAliasExample
Command Line--quit-after-disconnect--quit-after-disconnect
URIquit-after-disconnectqad{qad: true}

Note: Quit After Disconnect is Automatically Set

Quit After Disconnect is automatically selected when the following parameters are specified:

  • Username
  • Password
  • Domain
  • Connection Broker
  • Desktop

Set Host Resolution

This setting locks the resolution of your host application display.

Provide the value as a string, made up of the horizontal resolution, the letter "x", and the vertical resolution. For example, "1024x768".

This can only be configured on a single display.

OptionsDefaultType
A fixed resolution the host must use.Not setstring

Usage

MethodValidFullAliasExample
Command Line--set-host-resolution--set-host-resolution 1024x768
URIset-host-resolutionres{res: "1024x768"}

Setting Configuration Values via Config files

Certain advanced configuration values are set via configuration files, rather than via the user interface, command line, or URI methods. These files are read and implemented by the Software Client for macOS when it launches.

Configuration files can be saved in a system-scoped location, for settings that should apply to any Anyware client launched on a device, or a user-scoped location, for settings that should apply to specific users. If a setting is found at both levels, the user scope takes precedence.

Configuration files do not exist until a user changes a persistent setting via the user interface. If that has not occurred, you must create the file, either manually or using a deployment script.

Setting Config Values

Configuration values are set via plist settings. Each setting is specified by a write command:

User-scope setting:

defaults write "com.teradici.Teradici PCoIP Client" <Key> <value>

System-scope setting:

sudo defaults write "/Library/Preferences/com.teradici.Teradici PCoIP Client.plist" <Key> <value>

For example, the following file would add the USB device identified by the VID/PID pair 18a5,0302 to the local termination blacklist, causing it to revert to bridged connections:

defaults write "com.teradici.Teradici PCoIP Client" localtermination_black_list "18a5,0302"

Config File Locations

Depending on the desired scope, write settings to the plist file in one (or both) of these locations. Remember that the user-scoped file takes precedence over the system-scoped file:

ScopeLocation
System/Library/Preferences/com.teradici.Teradici PCoIP Client.plist
User~/Library/Preferences/com.teradici.Teradici PCoIP Client.plist

Disabling H.264 Hardware Decoding

  1. Open the Terminal app on the Mac client.

  2. Run the following command:

    defaults write ~/Library/Preferences/com.teradici.Teradici\ PCoIP\ Client.plist pcoip.enable_hw_h264=0
Configuring the Anyware Software Client (2024)

References

Top Articles
Latest Posts
Recommended Articles
Article information

Author: Jeremiah Abshire

Last Updated:

Views: 6490

Rating: 4.3 / 5 (54 voted)

Reviews: 93% of readers found this page helpful

Author information

Name: Jeremiah Abshire

Birthday: 1993-09-14

Address: Apt. 425 92748 Jannie Centers, Port Nikitaville, VT 82110

Phone: +8096210939894

Job: Lead Healthcare Manager

Hobby: Watching movies, Watching movies, Knapping, LARPing, Coffee roasting, Lacemaking, Gaming

Introduction: My name is Jeremiah Abshire, I am a outstanding, kind, clever, hilarious, curious, hilarious, outstanding person who loves writing and wants to share my knowledge and understanding with you.