Software Client for Windows Administrators' Guide

Configuring the Anyware Software Client for Windows

The Software Client for Windows 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 Windows 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):

"c:\Program Files (x86)\Teradici\PCoIP Client\bin\pcoip_client_cli.exe"  --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 Windows 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 Windows.
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:

  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.

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 Windows 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 system scope takes precedence.

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

Config File Syntax

The .ini file starts with a [General] group followed by a series of <key>=<value> pairs, each on its own line. 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:

[General]
localtermination_black_list="18a5,0302"

Config File Locations

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

Scope Location
System %PROGRAMDATA%\Teradici\Teradici PCoIP Client.ini
User %APPDATA%\Teradici\Teradici PCoIP Client.ini

Configurable Settings

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

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 Windows 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 Windows 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: disabled
false: 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 devices
False: 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 screen
false: 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 mode
False: 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: Critical
1: Error
2: Info
3: Debug
4: 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 Windows. 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: disabled
false: 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: disabled
false: 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 enabled
false: 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 enabled
false: 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 ratio
false: 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 Windows.The pre-session interface will not be available after disconnecting.

Options Default Type
True: Quit on disconnect
False: 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"}
Last updated: Thursday, July 18, 2024