Collaboration¶
The PCoIP Ultra Collaboration feature enables a PCoIP session user to share their session with a remote guest collaborator using standard PCoIP Soft Clients. While connected the guest collaborator can view the screen output and hear the audio output of the shared PCoIP session.
When discussing this feature, we'll refer to the first user as the host collaborator, and the second user who joins the session as the guest collaborator.
Requirements¶
-
The Collaboration feature must be hosted on a Graphics Agent for Linux 22.07 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 host and the guest collaborators must connect using a PCoIP Software Client 22.07 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 are not supported.
-
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 host on the configured collaboration port (UDP 64172 by default).
-
If the brokered connection is not via a PCoIP Security Gateway, then the guest collaborator's PCoIP client must be able to connect to the host on the configured collaboration port (UDP 64172 by default).
-
-
For unbrokered (direct) collaboration, the guest collaborator's PCoIP client must be able to connect to the host on the configured collaboration port (UDP 64172 by default).
Current Limitations¶
-
Only one guest collaborator can connect at a time.
-
Collaboration sessions support only one screen. The host collaborator should set their PCoIP Software Client to Fullscreen One Monitor mode prior to starting the collaboration session.
-
If the host and guest screen resolutions are different, the guest's screen will use scrollbars and letterboxing to display the shared content.
If high performance client mode is enabled, and if the host's resolution is greater than the guest's, the guest's screen will be clipped instead.
-
The guest collaborator's session can only view and listen to the shared session. The guest collaborator has no ability to control the host's keyboard, mouse, microphone, or any other input device.
-
Collaboration session tokens expire after 1 hour. The expiration time is not currently configurable.
-
Collaboration session tokens are single use. Once a collaboration guest has connected, a new token must be generated.
-
When a collaboration session is disconnected by the guest collaborator, the Stop Collaboration button in the Collaboration Management console may incorrectly remain enabled. If this occurs, click Stop Collaboration to reset the button state and allow a new collaboration session to be started.
-
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 host collaborator and all guest collaborators are using a PCoIP Client in Standard Client mode. The high performance client mode does not support mouse visiblity.
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 Graphics 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: 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 host collaborator starts a PCoIP session, then generates an invitation token that is passed to the guest collaborator:
-
Connect to a PCoIP session with PCoIP Ultra CPU Offload enabled.
-
From the remote session, open the Collaboration Management Console application:
-
Press Alt+Spacebar, type
PCoIP Collaboration
, and press Enter; or -
Find and launch the PCoIP Collaboration application from the task bar.
-
-
In the Collaboration Management Console, click Request a new invite.
Generating a new link and invite code
If you have already generated an invite but need to create a new one, click Stop Collaboration to invalidate the first invite and then click Start Collaboration to create a new one.
-
The Collaboration Management Console provides two pieces of information that are used to invite the guest collaborator:
-
Link: The guest collaborator will use this link to join your session. This URI may be opened on any Mac, Windows or Linux machine with a PCoIP Software Client 21.03 or newer.
This URI contains a collaboration token which will expire 1 hour after the Host session was established. The generated URI can only be used once. If the token expires, a new invite must be generated.
-
Invite Code: 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.
Note: Collaboration features have version requirements
Collaboration features such as Mouse Visibility are only available with PCoIP agents and software clients 22.07 or newer.
-
-
Share the PCoIP URI and the Collaboration Invitation Code with the guest collaborator.
Security best practice
We recommend that these two pieces of information be shared with the guest user in separate communications, reducing risk in the event that a message is inadvertently sent, forwarded, or intercepted by a third party.
-
When the guest collaborator attempts to join the session, the Collaboration Management Console 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 invite has been used and is now disabled. Subsequent attempts will require a new invite.
Joining a Collaboration Session¶
The guest collaborator can join the session once they have received the PCoIP URI and the Collaboration Invitation code.
-
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 Code. The value you enter for your name is used to tell the host who is joining; the Collaboration Invitation Code is the six digit number provided by the host. Enter both values and click Submit.
-
Once the host collaborator accepts your connection request, the Collaboaration screen share will start.
-
To leave the collaboration session, select Connection > Disconnect from the PCoIP Client menu.
Ending a Collaboration Session¶
The collaboration session will end when the host stops collaborating, or if either the host or guest collaborator disconnects their PCoIP connection.
To stop collaborating with a guest:
In the Collaboration Management Console, click the Stop Collaboration button. This ends the collaboration session. Once the session ends, the host can request a new invite 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 Graphics Agent for Linux is version 22.07 or later.
Currently, both host and guest collaborators must be using PCoIP Software clients running in standard client mode. High performance client mode does not currently support the Mouse Visibility.
Future releases will add the ability for the Guest Collaborator to take control of the session mouse and keyboard.