Configuring the PCoIP Software Client for macOS¶
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, or
- Via a URI, providing your configuration values in an encoded JWT string.
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-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:
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
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.
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 PCoIP 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 | — | — | — | — |
Security Mode¶
The security mode used for validating connections.
Note: This setting can be provided in the user interface
This setting is available from the user interface, in addition to the methods described here. For details, see PCoIP Software Client Security Modes.
Options | Default | Type |
---|---|---|
0 : Verification not required1 : Warn, but allow2 : Full verification required |
1 : Warn, but allow |
integer |
Usage
Method | Valid | Full | Alias | Example |
---|---|---|---|---|
Command Line | ✔ | --security-mode |
-s |
-s 2 |
URI | ✔ | security-mode |
sec |
{sec:2} |
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 PCoIP 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 PCoIP 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 {! ./_common/name.md! }.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} |
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"} |