Connecting Clients

Connect client for remote management

Using the pairing service

The fastest and easiest way to connect a new client with your RPort server instance is using the pairing service.

  1. Click on the gears icon in the top-right corner.

  2. Click on Client Access.

  3. Select one of the credentials and on that row click on Install Client.

  4. Copy the command snippet of the clients' operating system to the clipboard and paste it to a bash or PowerShell console of the machine you want to connect.

  5. Click the refresh icon on top of the client list.

Connect a Windows machine to the RPort server 📽️

Connect a Linux Machine to the RPort Server 📽️

Creating and using client credentials

How many credentials to create

By default, a fresh server installation comes with one randomly created pair of authentication id (aka username) and a password. This is good for securely connect the first client.

The client credentials can be used multiple times. Technically, it's possible to connect all client – even hundreds – with the same credentials. From a security perspective, this is not advised.

The communication is one-way. The server talks to the clients. Clients cannot dispatch any command or action to the server. And clients cannot communicate with each other. If you lose a device with the RPort client installed, a potential wrongdoer can read the client credentials, but he/she cannot really harm the server or other clients.

But a deny of service attack is possible by connecting thousands of new clients until the server runs out of memory. If credentials have fallen into the wrong hands, you should delete them immediately on the server. The more clients are using the deleted credentials, the more work you have to reconnect them with new credentials.

As a rule of thumb, you should create individual credentials for all desktops pcs and laptops and systems that are used by many users. For servers that are accessible only by a small team of system administrators, you can use credentials multiple times. Bear in mind, a system administrator might leave the company and take the credentials with him.

Credentials explained: What are all these ids?

Client credentials consist of an authentication id and a password. The id acts as the username to authenticate the client on connection. You can create numbered ids, or you can use meaningful names. Any string is suitable. The authentication id is not used for the later identification of the client. The client installer script will take the unique system identifier of the operating system and inserts it into the rport.conf file. Changing the client credentials will not change the client id. On the dashboard, the authentication id does not appear because it's not relevant for the identification of a client.

Client IDs and authentifcation IDs are different. Both can be changed idependently.

The client id can be changed at any time by editing the rport.conf file. If possible, you should avoid changing the client id. Data related to the clients, for example vault data or monitoring measurements, are tied to the client id. This data gets orphaned on changing a client id.

How is the pairing working?

RealVNC Ltd. – the creators of RPort – offers a free pairing service for any RPort server instance. Using the UI, you can click on “Install Client” on the “Client Access” menu. You will get a pop-up like this with a download URL starting with and ending with a random string.

The web-based user interface (not the server) takes the client credentials and uploads them over an encrypted HTTPS connection to the pairing service. A unique short random token is generated. Accessing the displayed pairing URL will generate an installer script that installs and configures the client with the credentials previously uploaded. This way, new clients can be installed in less than a minute.

Is it secure? 💬

Yes. The uploaded credentials are not stored to disk on the pairing server. They remain in memory for 10 minutes. No backups are performed.

Advanced pairing options

The pairing scripts accept command line parameters to modify the installation and the later execution of the rport client.

After downloading the pairing script but before executing it type in

sudo sh -h on Linux, to display the current help message

Usage [OPTION(s)]

-h  print this help message
-f  force, overwriting existing files and configurations
-v  print version
-t  use the latest unstable version (DANGEROUS!)
-u  uninstall the rport client and all configurations and logs
-x  enable unrestricted command execution in rport.conf
-s  create sudo rules to grant full root access to the rport user
-a  Use a different user account than 'rport'. Will be created if not present.

On Windows, type in Get-Help .\install.ps1 -full to read the help message. If you are asked if you want to update the entire PowerShell help database, answer "no".

PS C:\Users\Administrator\Documents> Get-Help .\install.ps1 -full


    Installs the rport clients and connects it to the server

    C:\Users\Administrator\Documents\install.ps1 [-x] [-t] [<CommonParameters>]

    This script will download the latest version of the rport client,
    create the configuration and connect to the server.
    You can change the configuration by editing C:\Program Files\rport\rport.conf
    Rport runs as a service with a local system account.

    -x [<SwitchParameter>]
        Enable the execution of scripts via rport.

        Required?                    false
        Position?                    named
        Default value                False
        Accept pipeline input?       false
        Accept wildcard characters?  false

    -t [<SwitchParameter>]
        Use the latest unstable development release. Dangerous!

        Required?                    false
        Position?                    named
        Default value                False
        Accept pipeline input?       false
        Accept wildcard characters?  false

        This cmdlet supports the common parameters: Verbose, Debug,
        ErrorAction, ErrorVariable, WarningAction, WarningVariable,
        OutBuffer, PipelineVariable, and OutVariable. For more information, see
        about_CommonParameters (

    None. You cannot pipe objects.

    System.String. Add-Extension returns success banner or a failure message.

    -------------------------- EXAMPLE 1 --------------------------

    PS>powershell -ExecutionPolicy Bypass -File .\rport-installer.ps1 -x

    Install and connext with script execution enabled.

    -------------------------- EXAMPLE 2 --------------------------

    PS>powershell -ExecutionPolicy Bypass -File .\rport-installer.ps1

    Install and connect with script execution disabled.

    Online help:

Last updated