Install the RPort client manually

Install the client on any device manually

Preface

While the preferred way to install the client is the pairing service, this option might not be feasible on devices with very limited resources. A shell like bash or many of the command line tools used for the automated creation of the configuration are very likely not available on devices likes routers, switches or NAS.

To run the client, you need two files.

1. The rport binary that matches the CPU architecture or your device

2. The rport.conf configuration file with all credentials and details of your rport server

Install the client binary

The most versatile way to install the client binary is downloading the tar.gz package for the release page of our GitHub repository to your desktop computer. Embedded devices might not be equipment with curl or wget and tools like tar and gzip might be missing too. So execute the download on your desktop and unpack the tar.gz file.

Either copy the unpacked rport client binary to a portable media such as an SD card or an usb stick. Or use sftp or scp to copy it via the network to the target. Many devices have the file system partially or entirely mounted read only. Look for a writable folder or attach a removable media.

Create the configuration

The download includes a file rport.conf.example. Rename it rport.conf and open it with an editor.

On Windows use notepad++ or some other editor that can handle Unix line breaks and Utf-8 encoding. The built-in windows' notepad is not suitable.

For a minimal configuration, you need to activate (uncomment) and change the following lines:

• server = Enter the IP address or the FQDN and the port of your RPort server. The port must be the port of the client interface. Do not use the port of the API or the User Interface. Usually, it's port 80. Example: server = "87bskdfsj.user.rport.io:80"

• fingerprint = Enter the fingerprint of your server. Go to Settings -> Info on the user interface to copy your fingerprint. Example: fingerprint = "2a:c3:79:09:81:ba:5c:60:15:e5:2f:92:6d:75:56:24"

• auth = Enter a client id (aka username) and the password, separated by a colon. Go to Settings -> Client Access on the user interface to copy both values. Example: auth = "client1:C@^Z#Iq3#8"

• id = Enter a unique identifier for the device. This id must be unique across all clients connected. On full operating system, the unique system or machine id taken. If your device has a file /etc/machine-id, take the id from there. If this file is missing, generate a random id using uuidgen or generate an id from your browser. Example id = "b30a82d4-a2ec-48f4-9314-31e2ee4e6ab8"

• name = Enter a human-readable name for the device you want to connect. Example name = "My-router-Cologne"

• allow_root = true You might need to run the client as root because creating a new user is not allowed. If possible, do not run as root. Check if you can use an unprivileged user.

• updates_interval = '0' Embedded system are not equipped with a package manager. To avoid errors being logged, switch the feature off.

• log_file = Enter a filename inside a writable folder. Examples: log_file = /mnt/usb/rport.conf or log_file = "/tmp/rport.conf

Run the client

If you have transferred both – the binary and the configuration – to the device, start a shell on that device. Either via SSH, Telnet or a serial connection. Execute the client via ./rport -c <PATH_TO_CONFIG>.

Check what is the preferred way to start service on boot. Hook in rport there.