Using Cloud connectivity tokens

Follow

CloudConnectivityToken
CloudConnectivityToken.png

To facilitate bulk deployment of your RealVNC Servers to the RealVNC Connect cloud, RealVNC Server can be joined to the cloud from the command line or via a script using a cloud connectivity token, instead of requiring a user to sign in to the RealVNC Server with their RealVNC account.

Computers can also be added to groups using cloud connectivity tokens if you need to restrict discovery of the computer to certain members of the team. 

Generating a cloud connectivity token 

Cloud connectivity tokens are found in the Device Access -> Deployment section of your RealVNC account. To generate a new cloud connectivity token use the Generate Token button in the Cloud connectivity tokens section.

mceclip1.png

Next, select how long the token will be valid for; either one hour or indefinitely.

 mceclip0.png

The token will be generated and will appear in the token column of the table.

mceclip0.png

The token can be applied either at install time (Windows only) or by using the command line/script for an existing RealVNC Server installation.

Deploying a cloud connectivity token

Please note that <TOKEN> should be replaced with the token you generated in the Deployment section of your RealVNC Account.

Alternatively, you can download a JSON file containing your token from the Deployment section, and replace <TOKEN> with the path to the downloaded JSON file.

Install time (Windows only)

From RealVNC Server 7.9.0 onwards, you can include a cloud connectivity token as an MSI property JOINCLOUD, for example:

msiexec /i VNC-Server-7.9.0.msi /qn JOINCLOUD=<TOKEN>

You can also specify which group(s) the RealVNC Server should be added to using the JOINGROUP property, and the name that the device should be given using the JOINNAME property.

When using JOINGROUP, the group must already exist in the RealVNC Connect Portal. You can specify multiple groups as a comma separated list.

For both JOINGROUP and JOINNAME, the values must be URL encoded, for example spaces become %20.

JOINCLOUD should only be set as part of a new/first installation. If included when upgrading an already cloud-joined RealVNC Server, a duplicate entry will be created in the cloud.

Command line

Windows

In an administrator / elevated command prompt run:

"%programfiles%\RealVNC\VNC Server\vncserver.exe" -service -joinCloud <TOKEN>

Mac

In Terminal:

sudo /Library/vnc/vncserver -service -joinCloud <TOKEN>

Linux

In a terminal application run:

sudo vncserver-x11 -service -joinCloud <TOKEN>

Script file

The following scripts must be run with elevated/administrator (Windows) or sudo/root (macOS and Linux) privileges.

Windows (Powershell)

To deploy a cloud connectivity token using a Powershell script, create a new Powershell file (text file saved with a .ps1 extension) with the following contents:

if ((& 'C:\Program Files\RealVNC\VNC Server\vncserver.exe' -service -cloudstatus | ConvertFrom-JSON | Select-Object -ExpandProperty CloudJoined) -eq $false){
  & "C:\Program Files\RealVNC\VNC Server\vncserver.exe" -service -joinCloud <TOKEN>
}

Windows (Command Prompt/batch)

To deploy a cloud connectivity token using a batch script, create a new batch file (text file saved with a .bat extension) with the following contents:

@ECHO OFF
"C:\Program Files\RealVNC\VNC Server\vncserver.exe" -service -cloudstatus | findstr CloudJoined | findstr false 1>nul
IF %ERRORLEVEL% EQU 0 (
  "C:\Program Files\RealVNC\VNC Server\vncserver.exe" -service -joinCloud <TOKEN>
)

macOS (Shell)

To deploy a cloud connectivity token using a shell script, create a new shell script file (text file saved with a .sh extension) with the following contents:

if [[ "$(/Library/vnc/vncserver -service -cloudstatus | grep CloudJoined | cut -f2 -d':' | tr -d ',')" = "false" ]]; then
  /Library/vnc/vncserver -service -joinCloud <TOKEN>
fi

Linux (Shell)

To deploy a cloud connectivity token using a shell script, create a new shell script file (text file saved with a .sh extension) with the following contents:

if [ "$(/usr/bin/vncserver-x11 -service -cloudstatus | grep CloudJoined | cut -f2 -d':' | tr -d ',')" = "false" ]; then
  /usr/bin/vncserver -service -joinCloud <TOKEN>
fi

Additional Options

Adding a computer to a group

To add a computer to a group using a token the option -joinGroup <GROUP> must be added to the end of the joinCloud command.

You need to replace <GROUP> with the name of the group the computer is to be added to. The group must exist in the RealVNC Connect Portal before it can be used by -joinGroup.

You can also specify that RealVNC Server should be added to multiple groups, by adding -joinGroup <GROUP> for each group you want to add RealVNC Server to.

Changing the name RealVNC Server uses when joining the cloud

RealVNC Server will use the computer's hostname when joining the cloud by default. To use a different name the option -joinName <NAME> must be added to the end of the joinCloud command.

You need to replace <NAME> with the name that you would like to use for the computer.

Negotiating proxy servers

If there’s an intermediate proxy server when you add a computer to a team, supply location and credentials. For example, under Windows:

  • SOCKS proxy server:
    vncserver.exe -service -proxyserver="socks://SERVER:PORT" -proxyusername=NAME -proxypassword=OBFUSCATED-PWD -joinCloud TOKEN
  • HTTP proxy server:
    vncserver.exe -service -proxyserver="http://SERVER:PORT" -proxyusername=NAME -proxypassword=OBFUSCATED-PWD -joinCloudTOKEN

If the proxy server requires a password, first obfuscate that password using the vncpasswd utility, located in the same directory as RealVNC Server. Run the following command, and follow the instructions:

vncpasswd -print
Was this article helpful?
5 out of 22 found this helpful

Comments

0 comments

Article is closed for comments.