Collaboration¶
Caution: Technology Preview feature
PCoIP Ultra Collaboration is provided as a Technology Preview feature for the Standard Agent for Linux during development. This means that features may not always work as expected, and behavior or interface elements may change without notice. We welcome your feedback! See our Technology Preview Program page for more information.
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 Standard Agent for Linux 22.04 or higher, with Collaboration and PCoIP Ultra CPU Offload enabled.
-
Both the host and the guest collaborators must connect using a PCoIP Software Client 22.04 or higher (macOS, Windows, or Linux).
-
Both collaborators must connect using PCoIP software clients that support PCoIP Ultra CPU Offload.
-
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.04 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.
-
The guest collaborator will not see the mouse cursor in the shared session.
-
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 as experimental features on the PCoIP Graphics Agent only. PCoIP Ultra GPU Offload and Auto Offload are not supported on the PCoIP Standard Agent.
Enabling Collaboration¶
The PCoIP Ultra Collaboration feature is disabled by default. To enable this feature, both PCoIP Ultra CPU Offload and Collaboration must be activated on the Standard Agent for Linux.
To activate PCoIP Ultra CPU Offload and Collaboration:
-
Open
/etc/pcoip-agent/pcoip-agent.conf
in a text editor. -
Add a new line enabling collaboration:
pcoip.enable_collaboration = 1
-
If CPU Offload is not already enabled, add a new line enabling it:
pcoip.ultra = 1
-
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.
-
On the Standard Agent for Linux machine, open a web browser and navigate to:
https://127.0.0.1:60443/collab
You will be prompted by a warning that the site you are visiting is not secure. Accept this warning and proceed to the page.
Important: Technology preview step
Accessing the Collaboration Console with a web browser is a temporary step for the technology preview. This will be replaced by a native collaboration console in a future release.
-
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.
-
-
Share the PCoIP URI and the Collaboration Invitation Code with the guest collaborator.
Security best practice
Teradici recommends 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.
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.
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.
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