Collaboration¶
The PCoIP Ultra Collaboration feature enables a PCoIP session user to share their session with a remote collaborator using standard PCoIP Software Clients.
While connected, the collaborator can view the screen output and hear the audio output of the shared PCoIP session, and optionally share control of the keyboard and mouse in-session. Collaborators do not automatically share input control; input control must be specifically granted by the session owner.
When discussing this feature, we'll refer to the first user as the session owner, and the second user who joins the session as the collaborator.
Note: Collaboration features have individual version requirements
Certain collaboration features, such as Mouse Visibility, are only available with PCoIP agents and software clients 23.01 or newer. To ensure feature compatibility, we recommend using the latest versions of PCoIP agents and PCoIP software clients.
Requirements¶
-
The Collaboration feature must be hosted on a PCoIP agent version 23.01 or higher, with Collaboration enabled, and:
- for Standard Agents, PCoIP Ultra CPU Offload must be enabled.
- for Graphics Agents, one of the Ultra offload modes must be enabled: CPU Offload, GPU Offload, or Auto Offload can all be used.
-
Both the session owner and the collaborators must connect using a PCoIP Software Client 23.01 or higher (macOS, Windows, or Linux).
-
Both collaborators must connect using PCoIP software clients that support PCoIP Ultra.
-
PCoIP Zero Clients and PCoIP Mobile Clients (iOS and Android) do not support Collaboration and cannot join collaboration sessions.
-
The PCoIP Software Client for macOS supports collaboration when running on Intel hardware. When running on Apple silicon (M1+), The PCoIP Software Client for macOS does not support Collaboration and cannot join collaboration sessions.
-
Collaboration sessions use a UDP port which must allow inbound traffic, both at the cloud provider network level and the local firewall.
The default collaboration port is UDP 64172; if necessary, this can be changed. See Changing the collaboration session port for details.
-
For brokered collaboration, the PCoIP Connection Manager and PCoIP Security Gateway 22.07 or later is required, and:
-
If the brokered connection is via the PCoIP Security Gateway, then the PCoIP Security Gateway must be able to connect to the session on the configured collaboration port (UDP 64172 by default).
-
If the brokered connection is not via a PCoIP Security Gateway, then the collaborator's PCoIP client must be able to connect to the session on the configured collaboration port (UDP 64172 by default).
-
-
For unbrokered (direct) collaboration, the collaborator's PCoIP client must be able to connect to the session on the configured collaboration port (UDP 64172 by default).
Current Limitations¶
-
Only one collaborator can connect at a time.
-
Collaboration sessions support sharing of one or more monitors, as follows:
-
Windowed mode: The session in the owner's client window will be shared.
-
Fullscreen One Monitor: The single fullscreen session will be shared. The session owner should set their PCoIP Software Client to Fullscreen One Monitor mode prior to starting the collaboration session.
-
Fullscreen All Monitors: All monitors will be shared, beginning with the Session Owner's monitor 1 and continuing up to the number of displays in the collaborator's system. The monitors that are shared cannot be configured, and are shared in system order.
When using this mode, the session owner should assume that the collaborator can see all displays unless a specific configuration has been tested and verified.
For example, if the session owner has four monitors and the collaborator only has two, the collaborator will see the session owner's first and second monitors. If the session owner and collaborator both have 2 displays, then both displays will be shared.
The session owner should set their PCoIP Software Client to Fullscreen All Monitors mode prior to starting the collaboration session.
-
-
If the session owner's and collaborator's screen resolutions are different, the collaborator's screen will use scrollbars and letterboxing to display the shared content.
If high performance client mode is enabled, and if the session owner's resolution is greater than the collaborator's, the collaborator's screen will be clipped instead.
-
By default, the collaborator's session can only view and listen to the shared session. Keyboard and mouse control can be shared with collaborators by enabling input control, described below.
-
Collaboration invitations expire after 1 hour. The expiration time is not currently configurable.
-
Collaboration invitations are single-use. Once a collaborator has connected, a new invitation must be generated.
-
Collaboration using PCoIP Ultra GPU Offload and Auto Offload are supported on the PCoIP Graphics Agent only. PCoIP Ultra GPU Offload and Auto Offload are not supported on the PCoIP Standard Agent.
-
HP Anyware Brokered Collaboration sessions are only supported when the session connection is made using the PCoIP Connection Manager 22.07 or later.
-
Collaboration Mouse Visibility only works when the session owner and all collaborators are using a PCoIP Client in Standard Client or High Performance (Preview) mode. The high performance client (Legacy) mode does not support mouse visiblity or input control.
Enabling Collaboration¶
The PCoIP Ultra Collaboration feature is disabled by default. To enable this feature, both PCoIP Ultra and Collaboration must be activated on the Standard Agent for Linux.
To activate PCoIP Ultra and Collaboration:
-
Open
/etc/pcoip-agent/pcoip-agent.conf
in a text editor. -
Add a new line enabling collaboration:
pcoip.enable_collaboration = 1
-
If PCoIP Ultra is not already enabled, add a new line enabling it by specifying a PCoIP Ultra Offload mode. The following example will enable CPU Offload:
pcoip.ultra = 1
Available values are:
pcoip.ultra = 1
: CPU Offload. This mode is available to standard and graphics agents.pcoip.ultra = 2
: GPU Offload. This mode is available only to graphics agents.pcoip.ultra = 3
: Auto Offload. This mode is available only to graphics agents.
-
Optional: To enable Collaboration Input Control if desired, stay in the text editor and follow the instructions in Enabling Input Control below.
-
Optional: The default port for collaboration sessions is UDP 64172. If you need to change the collaboration port number, add a new line specifying the new value:
pcoip.collaboration_udpport = <new_collaborator_port>
-
Save the file and exit the editor.
-
Restart the PCoIP Agent service:
sudo systemctl restart pcoip
See Configuration Guide - Configurable Settings for more detailed information on setting configuration values.
Hosting a Collaboration Session¶
To host a PCoIP Ultra Collaboration session, the session owner starts a PCoIP session, then generates an invitation token that is passed to the collaborator:
-
Connect to a PCoIP session with PCoIP Ultra and Collaboration enabled.
-
From the remote session, open the Collaboration Manager by clicking the Anyware Collaboration icon in the menu bar:
-
In the Collaboration manager, click Generate a new invitation.
Generating a new link and invitation passcode
If you have already generated an invitation but need to create a new one, click Stop Collaboration to invalidate the first invitation and then click Start Collaboration to create a new one.
-
The Collaboration manager displays the generated invitation:
The invitation contains two pieces of information that are used to invite the collaborator:
-
Invitation Link: The collaborator will use this link to join your session. The URI may be opened on any Mac, Windows or Linux machine with a PCoIP Software Client 21.07 or newer.
This URI contains a collaboration token which will expire 1 hour after creation. The generated URI can only be used once. If the token expires, a new invitation must be generated.
-
Invitation passcode: This is a 6-digit code that confirms the identity of the individual connecting to the collaboration session. A new code is generated along with each new token.
-
-
Share the invitation link and the invitation passcode with the collaborator.
-
To share both the link and the code at once, click the Copy invitation button. This will copy a single message, containing both the link and the code, which can be shared by email or messaging tool.
-
To share the link and code separately, click the copy button beside each item and share it individually.
Security best practice
We recommend that these two pieces of information be shared with the collaborator in separate communications, reducing risk in the event that a message is inadvertently sent, forwarded, or intercepted by a third party.
-
-
When the collaborator attempts to join the session, the Collaboration manager will display options to accept or reject the connection.
-
Click Accept to start the collaboration session. Click Decline to deny the request. Whether you accept the request or not, the invitation has been used and is now disabled. Subsequent attempts will require a new invitation.
Joining a Collaboration Session¶
The collaborator can join the session once they have received the PCoIP URI and the Collaboration Invitation passcode.
-
Open a web browser and go to the PCoIP URI shared with you (you may be able to click this link directly, depending on how it was shared with you).
-
The web browser will warn you that the link is attempting to open the PCoIP Client application. Allow the browser to open the PCoIP client.
-
When the PCoIP client opens, it will prompt you for your name and the Collaboration Invitation passcode. The value you enter for your name is used to tell the session owner who is joining; the Collaboration Invitation passcode is the six digit number provided by the session owner. Enter both values and click Submit.
-
Once the session owner accepts your connection request, the Collaboaration screen share will start.
-
To leave the collaboration session, select Connection > Disconnect from the PCoIP Client menu.
Collaborator Input Control¶
Collaborator input control allows the collaborator to use their mouse, keyboard, or other input device to control the session owner's desktop. This feature is disabled by default, and must be enabled on the PCoIP agent. Until it is enabled, the Can control option will be disabled:
Once enabled, the feature is available from the collaboration manager and can be activated by the session owner. ; note that This mode must be enabled by the session owner using the Collaboration Manager during a collaboration session; by default, the collaborator can only view the session.
Note: Disabling input control globally
You can disable Input Control on the PCoIP agent, which turns the feature off entirely. When disabled this way, session owners will not be able to allow collaborators to take control, and sessions will be view-only. For more information, see Disabling Input Control.
To allow a collaborator to control the session desktop:
-
From an active collaboration session, open the collaboration manager.
-
Beside the collaborator's name, click the dropdown menu and select Can control:
Taking Control¶
A collaborator who has input control can release it by idling—stopping all keyboard, mouse, and pointer activity—for a short time. Once the control timeout has elapsed, the floor is open, and whichever collaborator provides input next takes control.
By default, the control timeout is 3 seconds. The timeout value can be configured when enabling the input control feature, described below.
For example: the session owner has initial control of the session. In order to give control to the collaborator, the owner takes their hands off the keyboard and mouse for three seconds, allowing the control timeout to pass. The collaborator then moves their mouse, which gives them control. To give control back to the session owner, the collaborator takes their hands off their keyboard and mouse for three seconds. This exchange continues as long as desired.
Important: The session owner always has control of their PCoIP client's in-session menu
The session owner always has control of their PCoIP client's in-session menu. If the owner is unable to reclaim session input control for any reason, they can disconnect the PCoIP session using the in-session menu option. When the owner disconnects from the session, the collaborator is immediately disconnected.
Enabling Input Control¶
-
Using a text editor, open the following file:
/etc/pcoip-agent/pcoip-agent.conf
-
Add a new line enabling input control:
pcoip.enable_collaboration_input_control = 1
-
Optionally, provide a custom input control timeout value (specified in milliseconds; 3000ms is 3 seconds):
pcoip.collaboration_input_control_timeout = <timeout_value_in_ms>
-
Save the file and exit the text editor.
-
Restart the PCoIP agent service:
sudo systemctl restart pcoip
Disabling Input Control¶
-
Using a text editor, open the following file:
/etc/pcoip-agent/pcoip-agent.conf
-
Disable input control:
pcoip.enable_collaboration_input_control = 0
-
Save the file and exit the text editor.
-
Restart the PCoIP agent service:
sudo systemctl restart pcoip
Ending a Collaboration Session¶
The collaboration session will end when the session owner stops collaborating, or if either the owner or collaborator disconnects their PCoIP connection.
To stop collaborating:
In the Collaboration manager, click the Stop Collaboration button. This ends the collaboration session. Once the session ends, the session owner can request a new invitation and repeat the process above to start a new session.
Changing the Collaboration Session Port¶
The default UDP Port for collaborator sessions is 64172. If necessary, you can change this port.
To change the Collaboration session port:
- Open /etc/pcoip-agent/pcoip-agent.conf in a text editor.
-
Create new config entry specifying the new UDP port number to use:
pcoip.collaboration_udpport = <new_collaborator_port>
-
Save the file and exit the text editor.
-
Restart the PCoIP Agent service:
sudo systemctl restart pcoip
Mouse Visibility¶
Collaboration Mouse Visibility allows collaborators to see the other collaborator's mouse cursor movements. This feature is only available when both collaborators are using a PCoIP Software Client 22.07 or newer, and the Standard Agent for Linux is version 22.07 or later.
Currently, both the session owner and and collaborators must be using PCoIP Software clients running in standard client mode. High performance client mode does not currently support the Mouse Visibility.