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:
| Type | Format |
|---|---|
| Boolean | No value is required; the flag implies "True" |
| Numeric | Provide the parameter and then the numeric value, separated by a space. |
| String | Provide 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-screenThe 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:
| Segment | Description |
|---|---|
| pcoip:// | Required. This scheme is registered with the operating system and will launch the Software Client for macOS. |
| broker | Optional. FQDN of the connection broker to use. If the connection is not brokered, this can be omitted. |
| /connect | Required. 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:
- Create your configuration and credentials as a JSON object, using available configuration parameters and authentication credentials.
- Encode the object as a JWT token.
- Pass the token through the URI as the
dataparameter.
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.3MRUQ4VeKHbCnkG4OIXsUYp2N1IGf6AzTIo8tnFoXoAThe 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.
| Options | Default | Type |
|---|---|---|
| Interface language | English | string (short code or ISO code; see next table for options) |
Supported language options:
| Language | Short code | ISO code |
|---|---|---|
| Chinese Simplified | cn | zh_CN |
| English | en | en_US |
| French | fr | fr_FR |
| German | de | de_DE |
| Italian | it | it_IT |
| Japanese | ja | ja_JP |
| Korean | ko | ko_KR |
| Portuguese (Iberian) | pt | pt_PT |
| Spanish | es | es_ES |
Usage
| Method | Valid | Full | Alias | Example |
|---|---|---|---|---|
| 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).
| Values | Default | Type |
|---|---|---|
| The URL for the connection broker, if present | — | string |
Usage
| Method | Valid | Full | Alias | Example |
|---|---|---|---|---|
| Command Line | ✔ | --connection-broker | -b | -b broker.domain.com |
| URI | — | — | — | — |
Desktop
The name of the desktop to connect to.
| Values | Default | Type |
|---|---|---|
| The name of a desktop to conect to | — | string |
Usage
| Method | Valid | Full | Alias | Example |
|---|---|---|---|---|
| Command Line | ✔ | --desktop | — | --desktop myDesktop |
| URI | ✔ | desktop | vm | {vm: "myDesktop"} |
Domain
The domain to send to the connection broker.
| Options | Default | Type |
|---|---|---|
| The name of the domain to provide to the connection broker. | — | string |
Usage
| Method | Valid | Full | Alias | Example |
|---|---|---|---|---|
| Command Line | ✔ | --domain | -d | --domain domain.example.com |
| URI | ✔ | domain | dom | {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.
| Options | Default | Type |
|---|---|---|
| The URL for the Remote Workstation Card. | — | string |
Usage
| Method | Valid | Full | Alias | Example |
|---|---|---|---|---|
| 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.
| Options | Default | Type |
|---|---|---|
| A string password. | Not set | string |
Usage
| Method | Valid | Full | Alias | Example |
|---|---|---|---|---|
| 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.
| Options | Default | Type |
|---|---|---|
| The session ID to launch. | Not set | boolean |
Usage
| Method | Valid | Full | Alias | Example |
|---|---|---|---|---|
| Command Line | — | — | — | — |
| URI | ✔ | sessionid | sid | {sid: exampleSessionID} |
Username
The username sent to the Connection Broker.
| Options | Default | Type |
|---|---|---|
| The username to pass to the connection broker | Not set | string |
Usage
| Method | Valid | Full | Alias | Example |
|---|---|---|---|---|
| Command Line | ✔ | --username | -u | -u myUsername |
| URI | ✔ | username | usr | {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.
| Options | Default | Type |
|---|---|---|
true: disabledfalse: enabled | false (USB enabled) | boolean |
Usage
| Method | Valid | Full | Alias | Example |
|---|---|---|---|---|
| Command Line | ✔ | --disable-usb | — | --disable-usb |
| URI | ✔ | disable-usb | nousb | {nousb: true} |
USB Auto-Forward
This setting auto-forwards all non-HID devices to the host.
| Options | Default | Type |
|---|---|---|
True: Auto-forward USB devicesFalse: Do not auto-forward USB devices | False (do not auto-forward) | boolean |
Usage
| Method | Valid | Full | Alias | Example |
|---|---|---|---|---|
| Command Line | ✔ | --usb-auto-forward | — | --usb-auto-forward |
| URI | ✔ | usb-auto-forward | uaf | {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.
| Options | Default | Type |
|---|---|---|
| The list of VID,PID values to auto-forward | Not set | string |
Usage
| Method | Valid | Full | Alias | Example |
|---|---|---|---|---|
| Command Line | ✔ | --vidpid-auto-forward | — | --vidpid-auto-forward "aa11,bb22 cc33,dd44" |
| URI | ✔ | vidpid-auto-forward | vaf | {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.
| Options | Default | Type |
|---|---|---|
| The list of VID,PID values to block | Not set | string |
Usage
| Method | Valid | Full | Alias | Example |
|---|---|---|---|---|
| Command Line | ✔ | --vidpid-black-list | — | --vidpid-black-list "aa11,bb22 cc33,dd44" |
| URI | ✔ | vidpid-black-list | vbl | {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.
| Options | Default | Type |
|---|---|---|
true: full screenfalse: windowed | Not set (uses client's last-set mode) | boolean |
Usage
| Method | Valid | Full | Alias | Example |
|---|---|---|---|---|
| Command Line | ✔ | --fullscreen | -f | -f |
| URI | ✔ | fullscreen | full | {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.
| Options | Default | Type |
|---|---|---|
True: Launch in windowed modeFalse: Do not request windowed mode | False (does not request windowed mode) | boolean |
Usage
| Method | Valid | Full | Alias | Example |
|---|---|---|---|---|
| Command Line | ✔ | --windowed | -w | -w |
| URI | ✔ | windowed | win | {win: true} |
Log Settings
These settings control logging functionality, including verbosity and file location.
Log Folder
A custom location for client log files.
| Options | Default | Type |
|---|---|---|
| A valid system path to a folder | Not set | string |
Usage
| Method | Valid | Full | Alias | Example |
|---|---|---|---|---|
| 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).
| Options | Default | Type |
|---|---|---|
| A unique session identifier | Not set | string |
Usage
| Method | Valid | Full | Alias | Example |
|---|---|---|---|---|
| Command Line | ✔ | --log-id | — | --log-id abcde1234 |
| URI | — | — | — | — |
Log Level
Sets the log level. This parameter will override any existing configuration values.
| Options | Default | Type |
|---|---|---|
0: Critical1: Error2: Info3: Debug4: Verbose | Not set | integer |
Usage
| Method | Valid | Full | Alias | Example |
|---|---|---|---|---|
| Command Line | ✔ | --log-level | -l | -l 2 |
| URI | ✔ | log-level | logl | {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.
| Options | Default | Type |
|---|---|---|
| A prefix to use in generated log file names | Not set | string |
Usage
| Method | Valid | Full | Alias | Example |
|---|---|---|---|---|
| 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.
| Options | Default | Type |
|---|---|---|
true: disabledfalse: enabled | false (hotkeys enabled) | boolean |
Usage
| Method | Valid | Full | Alias | Example |
|---|---|---|---|---|
| Command Line | ✔ | --disable-hotkeys | — | --disable-hotkeys |
| URI | ✔ | disable-hotkeys | nohot | {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.
| Options | Default | Type |
|---|---|---|
true: disabledfalse: enabled | false (menu bar enabled) | boolean |
Usage
| Method | Valid | Full | Alias | Example |
|---|---|---|---|---|
| Command Line | ✔ | --disable-menubar | — | --disable-menubar |
| URI | ✔ | disable-menubar | nomenu | {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.
| Options | Default | Type |
|---|---|---|
true: scaling enabledfalse: scaling disabled | false (scaling disabled) | boolean |
Usage
| Method | Valid | Full | Alias | Example |
|---|---|---|---|---|
| Command Line | ✔ | --enable-scaling | — | --enable-scaling |
| URI | ✔ | enable-scaling | scale | {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.
| Options | Default | Type |
|---|---|---|
true: force enabledfalse: force disabled | false (Resolution force disabled) | boolean |
Usage
| Method | Valid | Full | Alias | Example |
|---|---|---|---|---|
| Command Line | ✔ | --force-native-resolution | — | --force-native-resolution |
| URI | ✔ | force-native-resolution | native | {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.
| Options | Default | Type |
|---|---|---|
true: Maintain aspect ratiofalse: Do not maintain aspect ratio | False (does not maintain aspect ratio) | boolean |
Usage
| Method | Valid | Full | Alias | Example |
|---|---|---|---|---|
| Command Line | ✔ | --maintan-aspect-ratio | — | --maintain-aspect-ratio |
| URI | ✔ | maintain-aspect-ratio | aspect | {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.
| Options | Default | Type |
|---|---|---|
True: Quit on disconnectFalse: Do not quit, show pre-session UI on disconnect | False (does not quit on disconnect) | string |
Usage
| Method | Valid | Full | Alias | Example |
|---|---|---|---|---|
| Command Line | ✔ | --quit-after-disconnect | — | --quit-after-disconnect |
| URI | ✔ | quit-after-disconnect | qad | {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.
| Options | Default | Type |
|---|---|---|
| A fixed resolution the host must use. | Not set | string |
Usage
| Method | Valid | Full | Alias | Example |
|---|---|---|---|---|
| Command Line | ✔ | --set-host-resolution | — | --set-host-resolution 1024x768 |
| URI | ✔ | set-host-resolution | res | {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:
| Scope | Location |
|---|---|
| System | /Library/Preferences/com.teradici.Teradici PCoIP Client.plist |
| User | ~/Library/Preferences/com.teradici.Teradici PCoIP Client.plist |
Disabling H.264 Hardware Decoding
Open the Terminal app on the Mac client.
Run the following command:
defaults write ~/Library/Preferences/com.teradici.Teradici\ PCoIP\ Client.plist pcoip.enable_hw_h264=0
