• RPort 1.0.1, 2023-10-25

• RPort 1.0.2, 2023-11-07

• RPort 1.0.3, 2024-01-05

• RPort 1.0.4, non-public release

• RPort 1.0.5, June 2024

• RPort 1.1.0, August 2024

• RPort 1.1.1, non-public patch release

• RPort 1.1.2, December 2024

This is a list of all available and upcoming features of RPort.

The current version is 1.0.5 released in June 2024.

Remote Access

• Get access to any remote device via a tunnelled TCP and/or UDP connections. RDP, SSH, and any other protocol become securely available for machines behind routers and firewalls.

• Any machine with the RPort client installed can act as a bridge, creating tunnels to any other IP address or host. This way you can easily manage routers, printers, switches or NAS systems inside remote networks. No VPN needed.

• Tunnels are protected with access control lists to prevent abuse.

• Tunnels for HTTP and HTTPS can be accessed via a new built-in reverse proxy. You will always have valid SSL certificates then.

• NoVnc integration. Get access to VNC servers directly in your browser.

• RealVNC integration to access devices via the latest version of the frame buffer protocol. With RPort and RealVNC Server you can securely access device anywhere without using the RealVNC Cloud broker. Read more.

• Web-RDP integration. Connect via Remote Desktop directly from the browser without opening external RDP clients.

• Tunnels and their destination can be restricted with fine-grained filters.

• Tunnels can be saved for reuse.

Inventory & Access rights

• The RPort dashboard always presents an up-to-date and comprehensive view of your entire inventory.

• Organize your machines and devices in folders grouped by branches, locations, roles, clients, etc.

• Get all details about the running operating system, CPU, and memory configuration from the dashboard.

• The dashboard shows the update status and all missing updates of the client. (Windows and Linux supported)

• Access to clients – scripts, commands, and tunnels – can be restricted to specific user groups.

• An audit log stores enables you to follow up on who did what and when. Retrace which command has been executed and what were the results.

• Fine-grained user permission model to control which commands a user group is allowed to execute and which remote ports/protocols are allowed to be used.

Monitoring

• A basic monitoring shows CPU and memory usage, all running processes and the fill levels of hard disk and mount points.

• Alerting and sending of notifications based on monitoring measurements and fine-grained rule sets.

Commands, Scripts & Files

• Short command or complex scripts can be executed without a prior interactive login directly from the browser. Learn more 🔖.

• Scripts and commands can be stored in a library for later reuse or for sharing with teammates.

• You can execute scripts and commands on many clients in parallel, with wide options for target filtering.

• Script and command results are streamed to the browser while execution is in progress

• On Windows, scripts can be based on cmd.exe (Batch), PowerShell (any version) or bash for Windows.

• On Unix, shebangs are supported, so Python, Perl, or any other interpreter installed on the remote system can be used.

• With the built-in Tacoscript, you can script even complex tasks with ease. Tacoscript is supported on Window and Linux without dependency on interpreters like Python. Learn more 🔖.

• RPort comes with a central server-side scheduler to execute scripts and commands at a given interval.

• With the file copy function, you can copy local files from your PC directly to a remote machine.

Vault

• The RPort database comes with an encrypted table for storing sensitive data like usernames and passwords.

• The master passphrase resides only in the memory of the running server. After a server restart, you must unlock the vault manually. This guarantees maximum privacy and protection.

• Enrich the metadata of a machine with any information like invoice numbers, serial numbers, vendor support hotline, and many more.

• ️ RPort comes with wiki pages per remote machine. This allows you to directly attach documentation to a host. Or you can use it as a logbook to share information on the team.

Client installation

• Clients are available for Linux, Windows, Mac with support of many architectures like ARM and MIPs.

• RPort consists of a single static binary without dependency to external libraries. Python or other scrip interpreters are not used. This makes RPort suitable for embedded devices. The client can run on Routers, Switches, and IoT appliances. (Linux Kernel and Shell access required)

• Clients do auto-registration. You can install the client directly on the remote machine without creating a configuration or a unique id on the server first. This makes mass deployment fast and comfortable.

• The server generates pairing codes and ready-to-use installation scripts for Unix shell and Windows PowerShell.

Miscellaneous

• The RPort server is protected by two-factor-authentication. The access to the API and the frontend can be secured by two-factor authentication using standard TOTP or tokens sent by email, webhooks, or pushover.

• The server has a built-in user management.

• Authentication can be delegated to a reverse proxy. This allows the integration into corporate authentication portals such as Netscaler, Keycloack, Caddy Auth Portal or the usage of Apache Authentication Plugins.

• For scripting and developing API clients, per-user token authentication is possible. Tokens can be limited to a read-only scope.

• Fast and direct log in to remote machines over RDP or SSH can be initiates directly from the command line with rportcli. Learn more 🔖.

• Clients can have a list of fallback servers. This allows you to implement a highly available setup.

• 🔥 With our cloud-installer, you can install the RPort server fully automated on all major cloud providers. 🧙‍♀️ Install now.

• Single Sign On

• You can add tags and labels to clients via the API/UI.

• HTTP/HTTPS based tunnels can be accessed by subdomains all on port 443 rather than random ports to achieve easy connectivity in corporate networks where outgoing traffic is limited to well-known ports. Read more.

Release Notes of RPort Server 1.1.0, RPort Client 1.1.0 and RPort Front End/Web UI - 1.1.0-5

Release date: August 2024

RPort Server and RPort Client

New Features 🚀

• Three new APIs have been introduced to support the new Job Status feature area. These are /jobs, /jobs/{job-id} and /jobs/{job-id}/latest. For more information, see the api-docs.

• Clients have been updated to support live job output buffer results when using the /jobs/{job-id}/latest API.

Improvements 🔩

• Clients no longer report a potential incompatible server warning message on connection disconnect

Fixes 🪛

• Much improved handling of clients re-connecting when already connected (due to SSH connection issues)

• Tunnels are now properly terminated by the server on client connection disconnect

• Clients no longer report connected tunnels when only loading client-side tunnel configuration

• OSVersion and OSFullName searches and filters now correctly handled

• Existing user sessions deleted when deleting a user

• Large job result buffers no longer cause SSH client server connection disconnects

Known Limitations 🪛

• The client send_back_limit is currently ignored for job output buffers. The maximum size of job results is 256000 bytes, which is the maximum size of a golang SSH global request message.

• The server is currently rporting an incorrect error message (Invalid Token: too many requests) when the user no longer has a valid session

RPort Front End/Web UI

New Features 🚀

• Added a new Job Status area at the top level. This makes it much easier to view the results of jobs (aka commands and scripts). If clients are also updated to 1.1.0 then it will be possible to see 'live' job output from the running job when viewing the job details via the Job Status area. Users will only be able to see the status and output of jobs that they have started, unless the server configuration (via show_all_jobs_for_permitted_clients) has been updated to allow visibility of all jobs for the clients that the user is permitted to manage.

Improvements 🔩

• When running commands/scripts, the job status/progress information has been improved

• Improved display of permission values

Fixes 🪛

• Clients with no IPv4 addresses could cause the client navigation / selection panel to get stuck on the spinner

• Session handling has been improved and a number of bugs fixed (although see Known Limitiations)

• Various package updates for security fixes

• When selecting clients for multi-job execution, empty brackets no longer shown if no group description

• Drag and drop in the Library is working again

Known Limitations 🪛

• Removed sessions (either via expiry or admin revocation) show an incorrect message of Invalid Token: too many requests and the user is not explicitly logged out. However, the user will not be able to interact with the server API any longer. Refresh the browser to be redirected to the login page.

RPort - an all-in-one remote management suite for heterogeneous environments. RPort addresses three basic needs of a sysadmin:

1. Fast and secure remote access from everywhere

2. script execution from a central dashboard

3. and automation of common tasks

RPort makes efficient automation doable for everyone.

RPort is an RMM software from RealVNC for remote access, remote management and automation of heterogeneous IT infrastructures. From public cloud-based to entirely protected and private.

With RPort you get remote access to all your servers, desktops and devices. Via remote desktop, SSH, VNC, and every other remote access protocol.

RPort is also excellent in automation of common tasks, like installing software, or applying updates. Just execute or schedule the right script from the built-in library. That allows you to execute even complex tasks quickly. You can fully automate tasks like software provisioning or operating system updates.

RPort's remote access function meets the highest security standards. Securely log in to the central dashboard using two-factor authentication.

The dashboard gives you a comprehensive overview of your entire infrastructure. You can access any remote machine from everywhere instantly. A VPN, a public IP address or port forwarding is not necessary. With RPort you can also access remote browser-based user interfaces as if they were on your local network. Tunnels will make remote ports available securely. These tunnels are protected by access control lists, so only you can access them.

All connectivity is achieved through a tiny client agent. RPort comes ready-to-use on Windows, macOS, and Linux. It’s ideal for accessing and controlling any type of device. No matter how small.

Release Notes of RPort Server 1.1.2, RPort Client 1.1.2 and RPort Front End/Web UI 1.1.2-2

Release date: December 2024

RPort Server and RPort Client

RPort Front End/Web UI

New Features 🚀

• None

Improvements 🔩

• Upgraded 3rd party packages for security.

Fixes 🪛

• Command / Script tags now saved properly.

• Prevent UI freeze when choosing fields for client groups and when no existing tags.

Known Limitations 🪛

Release 1.0.4 was not released as a public release.

RPort - an all-in-one remote management suite for heterogeneous environments. RPort addresses three basic needs of a sysadmin:

1. Fast and secure remote access from everywhere

2. script execution from a central dashboard

3. and automation of common tasks

😎RPort makes efficient remote access and automation doable for everyone.

RPort lets users manage and automate their Windows and Linux devices - desktops, servers, and any device from an intuitive browser-based dashboard. It provides a comprehensive overview of the entire inventory. Users can securely log in to remote systems. Firewall changes or a VPN are not needed.

RPort is made for maximum security. Sniffing credentials is technically not possible. Users always have full control over their data.

With RPort, Sysadmins can get into automation easily. Executing commands on remote machines from a central dashboard are the first step. On a single server or in a group, one by one or in parallel. Even complex tasks can be automated by scripts. A library allows reusing and sharing automation recipes with colleagues. Complete deployment of desktop PCs or servers including all applications and their configuration can be automated.

The underlying reverse tunnelling technology also makes remote access highly secure. Users connect to any remote system over an encrypted tunnel using Remote Desktop, SSH, VNC, HTTP, or any TCP-based protocol. No ports are exposed. No port forwarding or VPN is needed. Secure and proven login mechanisms of the OS are used. Unlike other solutions which operate via their own backdoors.

Users can install their RPort server easily, on-premise, or on any small cloud VM starting at $2 per month. Because the user always owns its RPort instances, no data is ever shared with a cloud provider. The remote client is lightweight and available for any operating system.

The Server and client are static binaries without dependencies, making the installation easy even for inexperienced users.

New features 🚀

• Alerting on monitoring data can be switched off at server level, resulting in a significant lower memory consumption.

Fixes 🪛

• The Log-out button works reliably now.

• All monitoring alerting rules can be deleted now.

• Timeouts on script execution are no longer ignored, which now makes the execution of scripts with an infinite duration possible.

• Suggested user passwords are now aligned with the server settings specified in the rportd.conf.

• Adding or removing a user to a user group doesn’t require a password update.

• The script and command editor can now handle unlimited long lines.

Improvements 🔩

• Real-time command and scripts response streaming on multi-client execution. The UI streams results while the scripts are still running.

• UX improvements on alerting rule management.

• The inventory view is now using the entire page width, giving you a more comprehensive overview.

New Features 🚀

• On multi-client command and script execution, you can now set a batch size.

• The licence status is displayed on the UI.

Improvements 🔩

• Improved pagination on long item lists in all areas

• Display of command and script results (single and multi-client)

• Client filtering now much more reliable

Fixes 🪛

• Broken determination of external IP addresses on Windows fixed

• Broken TLS min switch in server configuration file fixed

• Creating tunnels from the list of stored tunnels on fixed public ports fixed

• OS dark theme detection on documentation pages fixed

Release Notes of RPort Server 1.0.5, RPort Client 1.0.5 and RPort Front End/Web UI - 1.0.5-7

Release date: June 2024

RPort Server and RPort Client

New Features 🚀

• The server will now prevent users who have only been granted run scripts only permission from saving new scripts or updating existing scripts.

• RPort clients now have the possibility to use alternative connection profiles. See the rport.example.conf for more information.

Improvements 🔩

• Non-Admin users who have audit permissions will only see changes for clients that they have permission to handle. By default they will also only see audit logs for changes that they made. The new server setting show_all_audit_logs_for_permitted_clients will allow users to see changes made by other users for clients that they manage. See the rportd.example.conf for more information.

• The RPort Plus Plugin has been completely removed and all the related code migrated to the main rportd server code base. The plugin is no longer required to run the RPort server.

• It is now possible to set default timeouts for command and script execution separately. These defaults will also be provided to the RPort Front End which makes them the default when using the scripts and commands execution panels. See the rportd.example.conf for more information.

• If a client tunnel won't start, it doesn't prevent the client itself from starting. Instead an error is logged to the log file and the client continues to start.

• When using the api for client queries, additional sorting capabilities have been added. See the apidocs for more information.

• Using dashes in HTTP query urls has been deprecated and underscores should be used instead. Dashes are still supported but their use generates a deprecation warning in the server logs.

• API tokens are now hashed and stored using SHA256. The previous bcrypt encryption was too slow when running many scripts using API tokens. Migration of existing tokens to the new hashing algorithm is automatic.

Fixes 🪛

• The server no longer returns an error when the notification_scripts directory does not exist. Instead it returns an empty list.

• RPort client installs will no longer try to start the client before a valid config file is available.

• Uploading files is more reliable.

• When running jobs on Windows clients, processes are terminated cleanly if they exceed their allowed run time.

• Various security related fixes.

• Using rportd with command line parameters has multiple bug fixes.

• 'Execution ended' audit logs now include the name of the user that started the job.

• Fixed an issue related to updating ACLs on tunnels.

• Fixed an issue that would cause a server crash if a tunnel with an http proxy was creates without a specified scheme.

• Remote authorisation passwords are no longer included in the audit log

• Fixed a bug with mount point details in monitoring info sent to the server from clients

• Corrected a field name related to client external ip addresses.

RPort Front End/Web UI

New Features 🚀

• It is now possible to give permissions to users that only allows them to run scripts. Scripts can be loaded, viewed and run but not modified. This is implemented for both individual client and multi-client script execution. There is no change to the existing commands functionality.

Improvements 🔩

• The server configuration has been extended to allow default timeouts for both script and command execution. The RPort Front End will now use those defaults in both the command and script execution panels for both individual client and multi-client jobs.

• The start animation when first logging into RPort has been removed and the message displayed is now much simpler (just indicating whether no clients available or no clients selected).

• The width of the client connection status indicator has been increased to make it easier to see when a scrollbar is present on the client navigation panel.

• The minimum length of passwords is now obtained from the server and display when changing passwords in some panels. A future enhancement will ensure this retrieved minimum password length is displayed at most points where a password change is requested.

• Client names are now displayed in the audit log, instead of client IDs that can be less meaningful.

• Client searches now allow individual fields to be selected for searching.

• References to the RPort Plugin have been removed as all related functionality is now included in the main RPort Server code base.

Fixes 🪛

• When saving multi-client scripts and commands, it is now possible to save jobs where tags have been specified.

• When changing a password due to an enforced password change, the validation messages are now clearly displayed. Additionally, the password length is validated against the server configured minimum password length.

• When editing documents, the documents list is correctly refreshed after deleting a document.

• Fixed a minor issue with selecting columns when using multi-client execution.

• Fixed various issues with the inventory search panel.

• Various security related fixes.

• Fixed an issue where clicking outside of a modal dialog would close the browser window/tab

• Various fixes to file uploads.

• Fixed an autoscroll isues with multi-client job results.

• Fixed an issue where the option to save as for a script or command wasn't visible.

• The default RDP username should now be used as expected.

• Various fixes related to Client Groups.

• Screens where paging either wasn't working or isn't required have had the paging controls removed.

New Features 🚀

• Monitoring Alerts: You can now trigger alerts sent via email or custom scripts based on monitoring data.

• Optional external IP Address determination on the client side by using external IP APIs

Improvements 🔩

• SSH fingerprint backwards compatibility

Fixes 🪛

• Fixed broken metadata management.

• Fixed wrong date on reports for scheduled scripts.

• The dark theme has been removed while it's being reworked.

Create a virtual machine

Basic Settings

• From the Azure Service select "Virtual Machines".

• Click on Create > Virtual Machine

• Select an existing resource group or create a new one. If don't know what resource groups are, create a new one called rport.This avoids conflicts with existing resource groups.

• Enter rport-server as the name for the virtual machine.

• Select a region near you.

• Select "No infrastructure redundancy required" for the availability options.

• From the Image drop-down select Debian 11 "Bullseye" - Gen 1.

  You might need to click on "See all images" and type in "debian bullseye" into the search field.

• On the size-drop-down click "See all sizes" to get access to the cheap options. It's a bit challenging to find cheap VMs. Use the filters to display only VMs with 1-2 CPUs and 0-2GB RAM. Select a B1 or B1ls series (~3-7€/month)

• If you have SSH key pair, use it. Otherwise, select "Password" as the authentication type.

• Select a username other than root or admin. For example, superuser.

• Enter a strong password, if you are not using SSH keys.

• Do not change the inbound ports.

• Proceed to the next step, "Discs". Do not change anything and proceed to next step "Networking".

Networking

On the networking setup, select "Advanced" for the NIC network security group" and click "Create New" to create a new security group.

When creating the new network security group, add the following new inbound rules.

Now proceed to all the next steps without changing the pre-filled defaults.

Finally, create the new virtual machine.

After the machine has been created, click on "Go to resource" to get access to all details of the virtual machine.

Install the RPort server on your new Azure Virtual Server

From the details of the newly created virtual machine, grab the public IP address.

Connect over SSH to the instance using the username you specified during the VM creation. For example, ssh superuser@20.185.220.116. After the login, type in sudo -i to change to the root account.

👉 Now proceed to Install RPort on any virgin cloud VM

Prerequisites

We have created a fully automated installer, that converts any cloud-based virtual machine into a high-secure RPort server that is suitable for productive use.

To use the installer, you must fulfil the following prerequisites:

• You have an account at one of the supported cloud providers (if not, read below).

• You are familiar with SSH key-based authentication, and you know how to connect to a Linux-based virtual machine via SSH. Further knowledge of the Linux operating system is not needed.

🚀 Get started

It's quick and easy to launch your RPort server. Just two steps: Launch a new instance and fire the installer. That's it.

Select your cloud provider:

New to cloud computing?

Using virtual machines in the cloud is a no-brainer. Select one of the following providers. They are easy to manage for beginners. Unless company policies force you, we do not recommend starting cloud computing with AWS, Azure, or Google Compute. These are highly complex systems with advanced concepts. Getting started is anything but easy. On top, they are pricier. Our three recommended providers are a perfect choice to run a highly secure RPort server at a low price.

Select where you want to install your RPort server.

Some notes on sizing

Memory

The more clients you manage, the more memory you need. You can roughly calculate ~430 KB per Client.

CPU

Rportd does not consume many CPU resources. The smallest CPU on any cloud provider is suitable. Rport performs very well on a Raspberry Pi (armv7 and aarch/armv8)

Disk

Rport has built-in monitoring with retention of historical data. Each host writes ~16 MB data per day to the database. You can freely configure the retention period. If you want to manage many hosts with rport and if you require a long retention period, put large disks in your VM.

The fully automated installer will install the rport server on a virgin cloud VM. ✅ Suitable for any cloud vendor. ❎ Requires a dedicated public IP address.

The fully automated installer will install the rport server on any Linux system inside an intranet behind a NAT router. ✅ Suitable for any Linux and the Raspberry Pi. ❎ Uses no public IP address or port forwarding on the router.

Before you start your installation, make yourself familiar with the ports used by rport and their functions. It helps you to design your setup properly right from the beginning.

The port explanation below contains information how to change the ports inside the rportd.conf file and how to install the server with custom ports right from the beginning.

Install the RPort Server automatically

The server installer script will do all the tedious work for you. In no time, you'll have a perfect server that meets your exact requirements.

Alternatively, read the help message of the installer script.

curl -o rportd-installer.sh https://get.rport.io
sudo bash rportd-installer.sh -h

Pure intranet installation and operation

This example assumes you and your managed devices are located inside a local network (yellow area).

$ export RPORTD_LICENSE_ID=<YOUR-ID>
$ export RPORTD_LICENSE_KEY=<YOUR-KEY>
$ curl -o rportd-installer.sh https://get.rport.io
$ sudo bash rportd-installer.sh \
 --email user@example.com \
 --client-port 8000 \
 --api-port 5000 \
 --fqdn rport.localnet \
 --port-range 20000-20050

🧨 Caution You must enter a valid email address that will be used for the two-factor authentication. The email is stored only in your local database. The FQDN of the server must exist on your local DNS or at least enter it to /etc/hosts before you start the installation.

💁 Insider tip Use --totp instead of --email <EMAIL> to use two-factor authentication with mobile apps like Google or Mircosoft authenticator.

Security advice: Exporting your licence key to an environment variable via the export command can be insecure because the key could be extracted from the process list by currently logged in none-root users. To prevent this, create a text file, e.g. rportd-license-key.txt that contains the line export RPORTD_LICENSE_KEY=<YOUR-KEY>. Load the environment variables from the file with . ./rportd-license-key.txt and delete the file securely afterwards, e.g. using shred rportd-license-key.txt.

After the installation, you must import the root certificate of the rport server into your browser and operating system.

Intranet installation with internet operation

This example assumes the server is behind the firewall without a public IP address. The managed clients and the users are on the internet, accessing the server by the public FQDN of the router. Port forwarding is needed for TCP 80,443,20000-20050.

$ curl -o rportd-installer.sh https://get.rport.io
$ sudo bash rportd-installer.sh \
 --email user@example.com \
 --fqdn my-rport.dyndns.org \
 --port-range 20000-20050

💁 Insider tip The default http(s) ports 80 and 443 are used. If you create the DNS record and the port forwarding before you start the installation, Let's encrypt certificates are automatically generated.

Supported operating systems

The server installer only support the following Linux versions.

• Debian 10 & 11

• Rasbian 9 or newer

• Ubuntu 20.04 LTS or 22.04 LTS (⚠️ do not use none-LTS)

• RedHat, CentOS, Alma, Rocky, Oracle Linux 8

For all supported operating systems, the following architectures are supported: armv6, armv7, aarch64, X86_64.

CentOS Stream 9 is not yet supported due to a missing certbot package.

Ports used and their functions

1. Client connection port, [server] address = "<IP>:<PORT>" in the rportd.conf. The rport clients aka agents will connect to the server on this port. We suggest using port 80 because corporate networks usually do not block outgoing traffic on port 80. Plain HTTP is used, no certificates are needed. The encryption happens on application level and client and server handle it autonomously based on the SSH protocol over HTTP. You are welcome to use any other port, if firewalls allow outgoing connections over this port or if you plan to run the server and all clients on the same intranet. 🔅Use the server installer with --client-port <INT> to install your rport server on a different port than 80.

2. Client connection URL, [server] url = "http://<HOST>:<PORT>". This is an optional setting, only used to generate the pairing script for fast and easy client installation. The [server] url might differ from [server] address if port forwarding is used. The server might listen on 192.168.1.1:8080, but your clients will connect to the public DNS of your router, where a port forwarding is active. So [server] url might be http://rportserver.dyndns.org:8080, for example. By default, the server builds the client connection url with the FQDN and the client connection port. You must use this option if your remote systems are located outside your intranet (blue area) but you access the UI only from inside (yellow area) using an internal hostname. 🔅You can overwrite it with --client-url "http://<HOST>:<PORT>".

3. API & UI port, [api] address = "<IP>:<PORT>" in the rportd.conf. This is the port used for HTTPS connections to the dashboard, to connect the rportcli and to send API requests to. We strongly recommend using HTTPs. By using the default port 443 you achieve maximum accessibility from external networks. Using a different port than 443 is possible. Read the note about the SSL certificates. Even if you plan to access the user interface and the API only from inside your local intranet, do not turn off TLS/HTTPs. The rport server might have full root access to all clients. Sniffing your credentials over an unencrypted connection inside a local network is trivial. Credentials might give full access to all clients. 🔅 With --api-port <INT> you can instruct the server installer to use a different port than 443. The server installer will always enable HTTPS. Switching off encryption is not possible.

4. Remote access port range, [server] used_ports = ['20000-30000'] in the rportd.conf. These are the ports dynamically opened for the tunnels. This is where you connect your SSH, RDP, VNC, etc. clients to, to get access to the remote systems of the encrypted tunnel. The port range determines the maximum concurrently running tunnels. On a small setup, ten thousand might be too much. Please don't hesitate to use just a dozen. You can extend later. 🔅Use the sever installer with --port-range <START>-<END> - e.g. --port-range 5000-5010 to install the rport sever using just these ports.

Hostname and certificates

As already mentioned, we strongly advise using HTTPs even inside your local intranet. The installer will generate valid certificates for you. You won’t have a hassle with it. But to establish an HTTPs connection without warnings, 👉you must access the user interface or the API by hostname, and not by IP address. If you want to access the rport server from outside your local network, you need a public hostname. Almost all routers support a variety of dynamic DNS services to register a public hostname for you.

The server installer tries to first generate certificates using Let’s encrypt. The user interface can be opened from any browser anywhere without certificate errors. To use Let’s encrypt, two measures must be performed before you install the rport server.

1. Your public hostname must be registered, and it must resolve to the public IP address of your router.

2. A port forwarding for port 443 must be active. The external port 443 of the router must be forwarded to the port 443 of the rport server. That’s a requirement of Let’s encrypt. They deny issuing certificates if the validation is not performed over standard ports.

💡The installer has a self-signing fallback. If you prefer not to create port a forwarding on port 443 because perhaps the port is already in use, don’t worry. The installer will create a certificate authority just for Rport and a self-signed certificate is issued. You just need to import the CA into your OS or browser. Learn how.

Port forwarding

Which port forwarding you must create depends on your use case. If you plan to manage clients anywhere outside your local network, but you will access the user interface and the tunnels only from inside your intranet, a port forwarding for the client access port is sufficient.

✋Do not mess port mappings. It’s not recommended to use different ports externally and internally. The User interface and the client installer generate links and scripts based on the values of portd.conf. If you run the client connection port internally on 80, but you map it to the external port 8080, client connections will fail, unless you change the port manually in the client configuration file.

Start the installer 🪄

Now it's time to let the magic happen.

$ curl -o rportd-installer.sh https://get.rport.io
$ sudo bash rportd-installer.sh --fqdn rport.example.com

This is the simplest way to execute the installer. All default ports (read above) are used.

The help message indicates how to change the ports.

$ bash rportd-installer.sh -h
Usage rportd-installer.sh [OPTION(s)]

Options:
-h,--help  Print this help message
-f,--force  Force, overwriting existing files and configurations
-t,--unstable  Use the latest unstable version (DANGEROUS!)
-e,--email {EMAIL}  Don't ask for the email interactively
-d,--fqdn {FQDN}  Use a custom FQDN. Otherwise a random FQDN on *.users.rport.io will be created.
-u,--uninstall  Uninstall rportd and all related files
-c,--client-port {PORT} Use a different port than 80 for the client aka agent connections.
-d,--client-url {URL} Instruct clients to connect to this URL instead of {FQDN}
-a,--api-port {PORT} Use a different port than 443 for the API and the Web UI.
-s,--skip-nat Do not detect NAT and assume dire#ct internet connection with public IP address (e.g. one-to-one NAT).
-o,--totp Use time-based one time passwords (TOTP) instead of email for two-factor authentication
-n,--no-2fa Disable two factor authentification
-p,--port-range ports dynamically used for active tunnels. Default 20000-30000
-g,--skip-guacd Do not install a version of the Guacamole Proxy Daemon needed for RDP over web.

Manage certificates

Import the root certificate authority (root CA)

If the server installer can not use Let's encrypt to obtain certificates, a certificate authorities was created automatically. It's all stored in /etc/rport/ssl/ca/export. All users must import this root CA into their operating system and optionally directly into Firefox.

Transfer the Root CA file to your desktop. If scp is not an option, you can do an insecure download from http://<RPORT-SERVER-IP>:<PORT>/rport-ca.crt. The installer created a symbolic link, so the certificate is reachable via the built-in web server.

Import CA on Windows

Open PowerShell 7 and import the certificate. Chrome and Edge need to be re-opened afterwards. On PowerShell < 7, download the file with a browser and just to the import step.

iwr "https://<RPORT-SERVER-IP>:<PORT>/rport-ca.crt" -SkipCertificateCheck `
  -OutFile rport-ca.crt  
Import-Certificate -FilePath rport-ca.crt `
  -CertStoreLocation 'Cert:\CurrentUser\Root' -verbose

Import CA on macOS

curl -LOsk "https://<RPORT-SERVER-IP>:<PORT>/rport-ca.crt" 
sudo security add-trusted-cert -d \
 -r trustRoot -k /Library/Keychains/System.keychain rport-ca.crt

Import CA on RedHat-based Linux

sudo curl -sk "https://<RPORT-SERVER-IP>:<PORT>/rport-ca.crt" \
 -o /usr/share/pki/ca-trust-source/anchors/rport-ca.crt
sudo update-ca-trust extract

Import CA on Debian-based Linux

sudo curl -sk "https://<RPORT-SERVER-IP>:<PORT>/rport-ca.crt" \
 -o /usr/local/share/ca-certificates/rport-ca.crt
sudo update-ca-certificates

Create a new instance

• From the Compute Menu on the left side, select "Instances".

• Click on the green Plus sign to create a new instance.

• From the availability zones, select a region near you.

• On Step 2 "Select an Instance" click on the "Development" or the "Stardust" and select the smallest size available. (Stardust is not available in all regions)

• On Step 3, from the OS Images, select Debian Bullseye.

• On Step 4 (Volumes) do not add additional storage.

• On Step 5 enter rport-server as the instance name.

• On Step 6 make sure your SSH key is listed, of not abort and go to settings, to upload your SSH public key first.

Install the RPort server on your new scaleway instance

After the instance has been created, grab the ipv4 address from the summary page of the new instance.

Connect over SSH to the instance using the root user. For example, ssh root@51.158.191.191

👉 Now proceed to Install RPort on any virgin cloud VM

Create a virtual machine

• On the Google Cloud Platform dashboard go to Compute Engine/VM instances.

• Click the "CREATE INSTANCE" button.

• Enter rport-server as the name.

• Select a region near to you.

• Select General-purpose as machine family.

• Select N1 (Powered by Intel Skylake) as series

• f1-micro 1vCPU,614MB Memory) as machine type ~5.00 USD monthly estimate

• "Select Debian GNU/Linux 11 (bullseye)" as boot disk.

• On the firewall section enable "Allow HTTP" and "Allow HTTPS".

• Create the VM instance by clicking the Create button

Create a custom firewall

The default firewall is not suitable for the RPort server.

Go to VPC Network -> Firewall. Click on CREATE FIREWALL RULE on top of the existing rules. Create the firewall rule as shown on the screenshot. It's important to apply the rule only to specify the target tag rport-server.

Once the firewall has been created, go back to the settings of the virtual machine. Click on EDIT on the top. Scroll down to the Network Tags and enter rport-server. This attaches the newly created firewall rule to the VM. Click on Save at the bottom.

Install the RPort server on your new droplet

From the list of VM instances, grab the public ipv4 address of your newly created instance.

Connect over SSH to the instance using the root user. Usually, you must specify the private key created for the instance or the region. For example, ssh root@143.198.182.188

👉 Follow the generic instructions how to install RPort on a VM.

Update your VM first

It's always a good habit to apply all pending updates before installing the application. Also, reboot the machine to have the latest kernel with all security updates running.

apt-get update && apt-get -y dist-upgrade && reboot

Log in again using SSH and make sure 👉 you are the root user.

Install the RPort server

The installation of the RPort server consists of several steps. We compiled a handy script that does everything for you. 🪄 Fire it and let the magic begin.

export RPORTD_LICENSE_ID=<YOUR-ID>
export RPORTD_LICENSE_KEY=<YOUR-KEY>
curl https://get.rport.io -o rport-install.sh
bash rport-install.sh

⏱️ The script needs approximately 2 minutes to finish. If all goes well, you will get a URL and a random password for the login to the graphical user interface.

💁 Insider tip

You can start the installation with your own FQDN, for example bash rport-install.sh --fqdn rport.example.com. The FQDN must exist and it must reolve to the public IP address of your server.

If you ommit the FQDN a random hostname of the *.user.rport.io space will be created. You can change it later.

Security advice: Exporting your licence key to an environment variable via the export command can be insecure because the key could be extracted from the process list by currently logged in none-root users. To prevent this, create a text file, e.g. rportd-license-key.txt that contains the line export RPORTD_LICENSE_KEY=<YOUR-KEY>. Load the environment variables from the file with . ./rportd-license-key.txt and delete the file securely afterwards, e.g. using shred rportd-license-key.txt.

👉 Point your browser to the URL of your RPort server and log in with the user admin and the randomly created password. Check your inbox and grab the token for the two-factor authentication.

What's next?

After successfully starting your RPort server instance, you should

• 👉 Connect your first client

• 👉 Test the remote access

• 👉 Invite your team

• 👉 Perform regular backups

Use push messages for 2FA

RPort supports sending one-time tokens to mobile phones via Pushover. Pushover is a very tiny and versatile app available for Android and IOS.

You can use the app free for 30 days and after that trial it costs ~€6,00. This is a one-time payment. Receiving messages is free.

Install the app on your mobile and create your account. Or go to pushover and create your account there. Each person who wants to receive tokens on the mobile need its own Pushover account.

With a Pushover account, you are allowed to receive and to send messages. Only receiving is enabled by default. To set up the 2FA you need to enable sending too. This must be done only by one person, typically the main administrator of the RPort server.

Create your account and generate a token

Go to https://pushover.net and log in to your account (top-right corner). The credentials are the same on the mobile and on the web.

Scroll down to "Your Applications" and create a "new application/API Token". This enables sending messages.

Enter RPort as the name of the application and confirm the terms. A token is displayed. This is your sender token.

You now have

1. a user key, that is for receiving messages

2. And an application API token, that is for sending messages.

Test your key and token

Log in to your rport server via SSH and execute the following test command. You should receive a push message almost instantly on your mobile.

API_TOKEN=<APPLICATION_API_TOKEN>
USER_KEY=<YOUR_PERSONAL_KEY>
curl -s \
  --form-string "token=${API_TOKEN}" \
  --form-string "user=${USER_KEY}" \
  --form-string "message=hello world" \
  --form-string "title=Just a test" \
  https://api.pushover.net/1/messages.json

If the test message was sent successfully, proceed to the next step. If not, double-check you are using the right key and token.

Activate 2FA on the rport server

Open the configuration file /etc/rport/rportd.conf with an editor. Scroll down to the where two-factor is configured, and add the following lines.

two_fa_token_delivery = 'pushover'
two_fa_token_ttl_seconds = 600

Scroll further down to the [pushover] section and enter your API token and one user key. Restart the rport server with systemctl restart rportd.

If the server refuses to start, execute the following command to see what's going wrong.

su - rport -s /bin/bash -c "rportd -c /etc/rport/rportd.conf"

Update the database

If the server is running after you made the above changes – check with systemctl status rportd – enter at least one pushover user key to the database.

DB_FILE=/var/lib/rport/auth.db
USER_KEY=<YOUR_KEY>
cat <<EOF|sqlite3 $DB_FILE
UPDATE users SET two_fa_send_to="$USER_KEY" WHERE username="admin";
EOF

This will update the user key of the user admin. The keys of all other users can be updated via the web UI. Changing the database doesn't require a server restart.

Try to log in with your username and password. A message "Verify it's you" should appear, and your mobile should ring.

Create your DNS record

If you want to change the FQDN of a RPort server installed via the cloud-installer the first step is to create a DNS A Record that points to the IP address of your virtual machine.

The free DNS service of RPort will delete unused hostnames automatically, and your CNAME-record would become orphaned.

We will use rport-server.example.com as an example for the new hostname of your RPort server.

Login to the console of your rport-server using SSH and verify the new DNS record has been set up properly. Execute the following two commands. Both must print the same IP address – the IP address of your RPort server.

# Query the DNS
$ dig +short rport-server.example.com
51.15.51.42

# Fetch your external IP address
$ wget -qO - 'https://api.ipify.org?format=text'
51.15.51.42

Generate new SSL certificates

If you already have certificates for the new FQDN, you can skip this step.

Stop the RPort server first. To generate new free certificates via Let's Encrypt, execute the following commands.

systemctl stop rportd
FQDN=rport-server.example.com
# Generate
certbot certonly -d $FQDN -n \
  --agree-tos --standalone \
  --register-unsafely-without-email
# Change group ownerships so rport can read the files
chgrp rport /etc/letsencrypt/archive/
chmod g+rx /etc/letsencrypt/archive/
chgrp rport /etc/letsencrypt/live/
chmod g+rx /etc/letsencrypt/live/
chgrp rport /etc/letsencrypt/archive/$FQDN/
chmod g+rx /etc/letsencrypt/archive/$FQDN/
chgrp rport /etc/letsencrypt/archive/$FQDN/privkey1.pem
chmod g+rx /etc/letsencrypt/archive/$FQDN/privkey1.pem
chgrp rport /etc/letsencrypt/live/$FQDN/
ls -l /etc/letsencrypt/live/$FQDN/

Change the rportd configuration

Change the ssl key and cert

With the new certificates generated, or with your own certificates, open the configuration file /etc/rport/rportd.conf with an editor. Scroll down to the lines where certificates are configured. Certificates are registered twice. In the [server] and [api] section. Change it as shown.

Before (with random *users.rport.io FQDN)

# in the [server] section
tunnel_proxy_cert_file = "/etc/letsencrypt/live/14apzztqs96l.users.rport.io/fullchain.pem"
tunnel_proxy_key_file = "/etc/letsencrypt/live/14apzztqs96l.users.rport.io/privkey.pem" 
# in the [api] section
cert_file = "/etc/letsencrypt/live/14apzztqs96l.users.rport.io/fullchain.pem"
key_file = "/etc/letsencrypt/live/14apzztqs96l.users.rport.io/privkey.pem"

After (example with your FQDN)

# in the [server] section
tunnel_proxy_cert_file = "/etc/letsencrypt/live/rport-server.example.com/fullchain.pem"
tunnel_proxy_key_file = "/etc/letsencrypt/live/rport-server.example.com/privkey.pem" 
# in the [api] section
cert_file = "/etc/letsencrypt/live/rport-server.example.com/fullchain.pem"
key_file = "/etc/letsencrypt/live/rport-server.example.com/privkey.pem"

Change the client connect url

The rportd.conf file contains a setting url =, that indicates clients who is their server. You must change this setting to the new hostname. If the client url contains a hostname, you must change it. If it contains an IP address, no changes are needed.

Before (with random *users.rport.io FQDN)

url = "http://dtdu7j7pvaxv.users.rport.io:80"

After (example with your FQDN)

url = "rport-server.example.com"

Change the tunnel host

If your rport server runs behind a reverse proxy, can be your own or a service like CloudFlare, pay attention to the tunnel_host setting. Usually, you must specify an alternative hostname that points directly to your rport server, bypassing all reverse proxies.

Change the server URL for sending two-factor tokens via email

If your RPort server is using the default script to send two-factor tokens via email, you must enter the new URL of your server in /usr/local/bin/2fa-sender.sh too.

Open the script with an editor and enter the URL of your RPort server.

Before:

-F url=https://*.users.rport.io 2>&1)

After (example with your FQDN):

-F url=https://rport-server.example.com 2>&1)

Wildcards are not supported for custom domain names.

Chang the Totp name

Also consider changing the totp_account_name. When using TOTP as the second login factor, this field is filled. If you chose the FQDN of the server as the value for this field, this value should be changed in line with the new FQDN.

Start RPortd

Finally, start the rport server again with systemctl start rportd. Type in the new https://<NEW_FQDN> into your browser and check. 🎉

Remove unneeded certificates

After rportd is running again and uses the new certificates for the new FQDN, the old certificated should be removed. Otherwise, certbot would try to renew them too, at worst running into DNS resolution errors since the old FQDN doesn't exist any more. A proper clean-up can be achieved by running certbot delete and selecting the old cert via the corresponding number key.

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 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.

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 https://pairing.rport.io 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.

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 rport-installer.sh -h on Linux, to display the current help message

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".

Starting with RPort-Server 0.6.0 the NoVNC proxy and the NoVNC JavaScript client is included into the server. You directly connect to a remote VNC server from your browser. No VNC viewer is needed.

Using the NoVNC integration makes your VNC connection fully encrypted, even if the remote VNC server does not support encryption. The VNC "signal" is sent to the encrypted tunnel of rport from your remote machine to the rport server. The server transforms the signal into HTTPS.

Required VNC server settings

Accessing a server via NoVNC requires a VNC server running on the remote host. On Windows, any VNC server is suitable. On Ubuntu Linux, the built-in VNC server called Vino is known to be incompatible with RPort.

After installing a VNC server, activate the following settings:

• Turn off encryption. On TightVNC, encryption is not included, but others might have it. Encryption will be added via the RPort tunnel, the VNC server must accept unencrypted connections.

• Allow connection from localhost. Most VNC servers by default do not allow connection from localhost. Some call it loop back connection.

Using VNC® Server from RealVNC®

If you want to connect to RealVNC servers in a browser, this is supported with the release of noVNC 1.4.0. RealVNC system authentication is supported, and session encryption is achieved via the RPort tunnel.

To use this capability, please change the VNC Server “Encryption” to Prefer On. Either use the VNC Server UI or change the registry key Computer\HKEY_LOCAL_MACHINE\SOFTWARE\RealVNC\vncserver\Encryption to PreferOn. No further adjustments are required.

To access a RealVNC Server from the browser, select VNC as tunnel type, not RealVNC, and Enable NoVNC (VNC via Browser).

VNC Viewer and the Rport URL integration is required for Multifactor authentication, High-Speed Streaming, Audio and connecting to Virtual mode/Virtual Mode Daemon.

Create a virtual server

• Log in to your Hetzner Cloud Console.

• Select an existing project or create a new one.

• On the left menu select "Servers" and click on "ADD SERVER".

• Select a location near you. Hetzners connectivity is excellent. Servers in Finland or Germany are suitable for any customer in northern or Western Europe.

• For the OS IMAGE select Debian 11.

• Select "Standard" as type and "Network (CEPH)" as Storage Type. CEPH adds high availability to your server. Read More.

• Select the smallest size "CX11-CEPH".

• Do not add extra volumes.

• Do not add a network.

• Do not add a firewall.

• Do not add additional features.

• If you have an SSH key pair, add your public key. Using a traditional password for the log-in is possible, but less secure.

• Enter rport-server as the name for the virtual server.

• Click "Create & buy now"

Install the RPort server on your new Hetzner Virtual Server

From the list of servers, grab the public ipv4 address of your newly created server.

Connect over SSH to the instance using the root user. If you have created the server without an SSH public key, look for an email with the root password. If you log in with a password, you are forced to change the password on the first login.

👉 Now proceed to Install RPort on any virgin cloud VM

Start a new instance

Because RPort has almost no dependencies, it will run flawlessly on any halfway modern Linux. We recommend using Debian 11 Bullseye. Debian is lightweight and secure.

• Log in to your AWS console, go to ECS and select your preferred region.

• Click "Launch Instances" and type Debian Bullseye into the search bar.

• Click on "N results in AWS Marketplace"

• Look for the official Debian logo and select Debian 11 provided by Debian.

The RPort server doesn't require a lot of CPU, disk, or memory resources. Selecting a t2.micro instance is perfect. ✋Do not launch the instance yet. Click "Next: Configure Instance Details".

On "Step 3: Configure Instance Details" you don't have to change anything. Take over all the pre-selected defaults. Click "Next: Add Storage".

On "Step 4: Add Storage" you don't have to change anything. 8 GiB is fairly enough disk storage. Take over all the pre-selected defaults. Click "Next: Add Tags".

On "Step 5: Add Tags" you don't have to change anything. But feel free to add tags to keep your ECS instance well organized. Click "Next: Configure Security Group".

On "Step 6: Configure Security Group" setting up the security group is crucial. Enter the following settings.

After creating the security group click "Review and launch".

Now click "Launch" to launch the instance. On the last step select which SSH keys to use. The decision is up to you. Finally, launch the instance.

Install the RPort server on your new ECS2 instance

From the list of instances, grab the public ipv4 address of your newly created instance.

Connect over SSH to the instance using the admin user. Usually, you must specify the private key created for the instance or the region. For example, ssh -i .ssh/ec2-ohio.pem admin@18.221.7.172

After the login, change to the root account by typing in sudo -i.

👉 Now proceed to Install RPort on any virgin cloud VM

Create a tunnel

To log in to a remote system located behind a firewall or NAT router, you need a tunnel.

Select the client you want to access, and click on the green button ADD TUNNEL. Depending on the operating system, the dialogue is prefilled with defaults you very likely would like to use. For Windows, an RDP tunnel is suggested, and for Linux SSH is used as default. The tunnel will be protected with an access control list that gives access only to your current IP address. This ACL is a second layer of security. Valid login credentials are still required.

By clicking ADD TUNNEL the connection is created instantly. Now click on the LAUNCH TUNNEL icon and your default application for RDP or SSH opens the connection. From now on, use the username and password of the system you already have.

For RDP, a configuration file for the remote desktop client is generated and downloaded. Look at the downloads of your browser and double-click.

What are those tunnels?

Create and use a tunnel

Use tunnels to access remote servers and devices over SSH, remote desktop or any other TCP-based protocol. The tunnels are reverse tunnels initiated by the remote side. That means the IP address of the remote system doesn't matter and the remote side doesn't open any additional ports. The tunnel is created through the HTTP protocol. As long as the remote client is allowed to access the internet via HTTP, you can create tunnels.

Create the tunnel

• Select a client on the left side, and click on it. Select the tunnels tab.

• Click the Add Tunnel button.

• Select the service you want to access on the remote client.

• After the tunnel is created, the remote port – for example the port 3389 of the remote desktop – becomes available on a random port of the rport server. If you would like to use a specific port instead of a random, you can do so.

• Usually, only you intend to use the tunnel. Therefore, your current public IP address is prefilled into the access control list (ACL). If you intend to enable public access to a web server inside an intranet, for example, you can switch of the ACL completely.

• If you would like to keep tunnels alive, even they are not actively used, unselect the "Close tunnel after inactivity of N minutes" option.

• Optionally, you can close (destroy) the tunnel even if it's still in use after a given period.

Launch a tunnel from the browser

After the tunnel has been created, you can use it in different ways. The fastest and easiest way is clicking on the "Launch Tunnel" icon.

Depending on the selected protocol (scheme) your browser will launch the application registered as default application (handler) for that scheme. For example, on Linux and Mac desktops, all links with a ssh:// scheme will be opened in a terminal that automatically starts the ssh client. You can achieve this behavior on Windows too. Learn how.

Remote desktop connections will not directly open from the browser. Clicking on the "Launch Tunnel" button triggers the download of an RDP configuration file. This file contains all details for the connection. Just double-click on it. On Windows and Mac the Microsoft Remote Desktop opens and connects you. On Linux Remmina should open. If not, make Remmina the default application for *.rdp files.

Use a tunnel manually

A tunnel consists of two ends. On the remote side, it ends on TCP port of a rport client. (Read below if the tunnel should not end on the rport client.) The other end of the tunnel ends on the rport server on an arbitrary port, either randomly selected or specified manually. But generally the tunnel does not end on the default ports assigned to the protocol, like 22 for SSH or 3389 for RDP.

On the above example, a tunnel is created to the SSH port of a remote Linux server. The rport server has tied the other end of the tunnel to the port 29304. Let's say your RPort server has the FQDN rport.example.com. To access the remote Linux server via SSH use ssh -p 29304 user@rport.example.com.

If you want to connect the remote desk client to the public end of a tunnel, specify the port after the server name, separated by a colon.

Service forwardings

A so-called service forwarding allows you to access resources on a remote network where the rport client is not installed or cannot be installed. A typical use case is getting access to configuration of routers, switches and printers. But a service forwarding is also used to access SSH or RDP on servers, where the rport client cannot run. Any rport client can act as a bridge, creating a service forwarding to external TCP ports.

Look at the example to understand how it works.

• The rport client runs on a host called ITXC located in a 192.168.249.0/24 subnet.

• The tunnel will create a service forwarding for the RDP port to a neighbor server with the IP address 192.168.249.33.

• The service forwarding will be stored in the library. Using this feature, you and your teammates can re-launch the service forwarding with a single click, without entering all the details again.

Built-in HTTP reverse proxy

Starting with RPort 0.5.0 the rport server comes with a built-in HTTP reverse proxy. This reverse proxy can be activated for all tunnels using the http or https scheme.

A typical use case is accessing web-based configurations inside an intranet. You could access any TCP port without a proxy with previous versions, but the new proxy option brings two significant advantages:

1. All communication from your browser to the end of the tunnel on the rport server is encrypted using HTTPS with valid certificates that doesn't confuse users with warnings.

2. If the tunnel points to an HTTPS target with invalid certificates, the proxy puts valid certificates on top, avoiding warnings and unsecure communication.

RPort servers >= 0.5.0 installed with the automated installer script and the hosted version have the reverse proxy function enabled by default. If you have upgraded from older versions, read how to enable the function.

❗The proxy will always listen on a secure HTTPS port on the public side. Using the proxy without encryption is not supported.

Create tunnel with an HTTP reverse proxy

On the creation of a tunnel, just activate Enable HTTP Reverse Proxy. 👀Pay attention to the optional host-header. Many web servers use so-called virtual hosts. If the connection does not specify the right host – the name of the site you want to access – the connection might fail, or you land on some default site. Use the domain that you would use to access the site without a tunnel as host-header.

The below example shows how to access the web-based configuration of a router through a tunnel. Because without a tunnel, you would access the router by its internal host name fritz.box this name is used as host-header.

Access remote sites through the reverse proxy

After the tunnel is created, the "exposed port" is where the proxy listens. All requests are forwarded to the end of the tunnel. Clicking the "Launch Tunnel" icon will open a new browser windows or tab on the exposed port.

Built-In NoVNC integration

Starting with RPort-Server 0.6.0 the NoVNC proxy and the NoVNC javascript client is included into the server. You directly connect to a remote VNC server from your browser. No VNC viewer is needed. Read more

Starting with RPort-Server 0.6.0 the Guacamole Server and a pure JavaScript client is included into the RPort server. You directly connect to a remote desktop or terminal server from your browser. No desktop app is needed.

Using RDP via browser, your RDP connection fully encrypted.

Starting with RPort version 0.9.0 an integration with VNC® Viewer from RealVNC® is built-in.

Prerequisite

Create the tunnel and launch the app

On the "Add tunnel" dialogue, select "RealVNC". Port 5900 is used by default. Change only if needed. Start the tunnel with the ADD TUNNEL button.

Once the tunnel has been created, click on the Launch Tunnel icon.

If you do this for the first time, your browser will ask for a confirmation. You must approve the browser shall open a desktop app. Click Open. If you plan to use VNC® Viewer from RealVNC® often, also activate the checkbox "Always allow ..."

Done! VNC® Viewer from RealVNC® should open and connect you to the remote system.

Use the tunnel with older versions of VNC® Viewer from RealVNC®

If your version of VNC® Viewer from RealVNC® does not support browser integration, start VNC® Viewer from RealVNC® manually. On the list of tunnels, click the Copy to clipboard icon. Put your cursor in the address bar of the viewer and paste from the clipboard. Hit enter to start the connection.

Create a droplet

1. On the top right corner click the green "Create" button and click on "Droplets". You are asked some questions about your new droplet.

2. On "Distributions" select "Debian 10 x64".

3. For the plan select "Basic".

4. For the CPU options select "Regular Intel with SSD". (We don't need a high-performance droplet.)

5. Select the smallest VM (1GB/1CPU(25GB SSD(100GB transfer) ~$5/Month

6. Do not add extra block storage.

7. Select a data center region near you.

8. Don't change the default settings of the VPC network.

9. Either select an SSH Key for the authentication or choose authentication by a password.

10. Enter RPort-Server as the hostname for the new droplet.

11. Optionally add tags or assign the new droplet to a project.

Install the RPort server on your new droplet

From the list of droplets grab the public ipv4 address of your newly created instance.

Connect over SSH to the instance using the root user. Usually, you must specify the private key created for the instance or the region. For example ssh root@143.198.182.188

After the login, install the curl command because it's a prerequisite for all further steps.

Why 2FA and which to choose?

The more devices you manage with RPort the more powerful the RPort server becomes. If an unauthorized person get access to it, this person might take over partial or full control over your infrastructure. Getting access to your machines via RDP or SSH always requires login credentials of the operating system. But if you have scripts and command enabled, full control might be possible from the RPort dashboard.

Enabling two-factor authentication is therefore recommended. It prevents unauthorized usage of the RPort server if you or your teammates use weak passwords or passwords are stolen.

With 2FA enabled, you will receive a one-time token after the regular log in.

The RPort server supports four two-factor-authentication methods

1. Sending the second factor, a one-time-token, via email using an SMTP server.

2. Handing over the token to a script, and you implement your own sending mechanism.

4. Using a rfc6238 one-time-token generate by standard apps like Google or Microsoft authenticator.

Using email is free of cost, but the protection is weaker compared to a push message. Think of a lost or stolen laptop. If the laptop is not fully encrypted, the wrongdoer will have access to RPort and the email account. The 2FA is useless. If you select push messages for 2FA the wrongdoer must get access to the laptop and the mobile phone. And nowadays, mobiles are protected biometrical, so accessing the token is not that easy.

• 👉 Use email for 2FA

free two-factor sending service

Starting with rportd version 0.3 (late August 2021) all rport cloud installations have two-factor authentication via email enabled by default. Emails are sent via a free public service. This is good to start with a secure setup right from the beginning. The service comes without warranty or promised availability.

Privacy notes

Use the free service on manual installations

If you have installed your RPort server manually, and you want to use the free token service, create the script with the following content.

In your rportd.conf insert the following lines to the [api] block.

Create a new instance (virtual machine)

• On the Vultr desktop, select Products and click on the instance tab.

• Use the Plus sign on the right side to create a new instance. Click on "Deploy new server".

• Select a region near you.

• Choose the smallest size available, that will cost you 5$USD per month.

• Do not add any additional features.

• If you haven't uploaded your public SSH key yet, do so. Vultr does not support log in via password.

Log in via SSH

After the instance has been deployed, grab the public IP address from the list of instances.

Log in to the instance using SSH and the root user, for example, ssh root@45.76.82.9.

Prepare the instance

Vultr installs the Exim Email-Server by default. It's not needed for RPort. 🧹 Keep your system tidy and uninstall it with apt purge -y exim4-*.

Create a Firewall

• Add the following rules

  • Accept SSH 22 Anywhere 0.0.0.0/0

  • Accept TCP(HTTP) 80 Anywhere 0.0.0.0/0

  • Accept TCP(HTTPS) 443 Anywhere 0.0.0.0/0

  • Accept TCP 20000-3000 Anywhere 0.0.0.0/0

  • Accept ICMP - Anywhere 0.0.0.0/0 👈 Do not skip this rule!

  • Drop any 0-65535 0.0.0.0/0

Finally, click on Linked Instances, select the rport server and link it to the new firewall by clicking the plus sign.

Install the RPort server

👉 Now proceed to Install RPort on any virgin cloud VM

What are the defaults?

Using the pairing method, you are not asked to give the client a name. The installer uses the local short hostname of the operating system to create the initial configuration.

Furthermore, a client gets two tags by default. The current country and city taken from the current public IP address. This might not be accurate and you may want to delete or change it.

Changing the client name and tags

If you want to change the name of a system, you must do this in the rport client configuration file. The configuration files is /etc/rport/rport.conf on Linux C:\Program Files\rport\rport.conf on Windows

Open the file with a text editor. Scroll done some lines. You will find the setting name = "<SOME-NAME>". Change the name to your needs.

Just a few lines below the name, you'll find the tags. Change them to your needs and save the changes.

Restart the RPort client

After any changes to the configuration file, you need to restart the client.

On Linux, execute systemctl restart rport.

On Windows use the service manager or from a PowerShell console execute: restart-service rport. If you prefer the old cmd.exe console, use net stop rport and net start rport.

Preface

The rport server has a built-in key-value store based on an encrypted sqlite database. A passphrase – the so-called master key – is needed for encryption and decryption. This master-key resides only in the memory of the rport server and is not stored on the hard disk or any other permanent storage.

Only the values of the key-value store are encrypted. Keys are stored plain text.

Initialize the vault

After a fresh installation, the vault needs to be initialized.

To change between the different two-factor-authentication methods, you must open the configuration file locate on your rport server at /etc/rport/rportd.conf with a text editor.

Scroll down and look for the examples of TOTP. Remove the comment (hash) signs so your configuration looks like the sample below:

👉 Very likely, you will have some other 2fa default method enabled. You must disable it. Look for the line two_fa_token_delivery = 'smtp' or two_fa_token_delivery = '/usr/local/bin/2fa-sender.sh'. Put a comment (hash sign) at the beginning of the line to disable it.

After having done the changes, restart the rport server by executing systemctl restart rportd.

Now open the user interface in your browser and login in with username and password. You will be prompted to scan the QR code with your authenticator app, or you can copy the secret to your desktop app. The secret is displayed just once.

From now on, you must always enter your username, the password and a token generated by the authenticator app.

Create a group

To create a client group, navigate to Settings, and select Client Groups. Click on the button ADD GROUP.

Enter the ID of the new group. (This will be the group name). This ID will appear in the client list on the left side. We will use the id "Fileservers" in this example. Spaces are not allowed in the group ID. Optionally, you can enter a description for the group.

Next is adding at least one filter on the members tab, that determines which clients are the members of the group. You can use many criteria. The most command one is the client name.

You can add individual clients to the group by ticking on the checkboxes. Using wildcards is also supported. So, a filter could be "Hostname is E*"

With the above example, any new client whose name stars with "E" or "F" and whose IP address starts with "10" will automatically become a member of the group.

SSH Link handler for Windows

RPort and your browser will open links to ssh://user@remote.example.com with the default application for that URL scheme. Windows does not have any default application assigned. To do so, follow the guide below.

Step 1: Install OpenSSH

Make sure you have OpenSSH installed on Windows 10. Open a terminal (cmd.exe or PowerShell) and type in shh -V. You should get an output similar to

OpenSSH_for_Windows_7.7p1, LibreSSL 2.6.5

If the ssh command is missing, execute the following command on a PowerShell.

# Install the OpenSSH Client
Add-WindowsCapability -Online -Name OpenSSH.Client~~~~0.0.1.0

More info here

Step 2: Download the wrapper script

An ssh link follows this syntax, ssh://<username>@<host>:<port> but open ssh expects a different format. Download the PowerShell script ssh-protocol-handler.ps1 to some directory, for example to %LOCALAPPDATA%\ssh-protocol-handler.ps1.

You can do this on the PowerShell with the following commands.

$url = "https://gist.githubusercontent.com/thorstenkramm/b25a2c09ca7414595d48d1db581833fc/raw/1fecf170378390eebe778209a8b88972d6893657/ssh-protocol-handler.ps1"
$file = "$env:LOCALAPPDATA\ssh-protocol-handler.ps1"
[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
Invoke-WebRequest -Uri $url -OutFile $file

Test the script by executing .\ssh-protocol-handler.ps1 ssh://user@127.0.0.1:22. It doesn't matter if you have a local SSH server. It's just for testing the URI gets translated into the correct PowerShell command.

Step 3: Register the script as URL handler

Download the ssh-protocol-handler.reg registry setting file. Adding it to the registry will register the above script as a protocol handler for ssh:// links.

You can do this in the PowerShell with the following commands.

$url = "https://gist.githubusercontent.com/thorstenkramm/b25a2c09ca7414595d48d1db581833fc/raw/1fecf170378390eebe778209a8b88972d6893657/ssh-protocol-handler.reg"
$file = "$env:LOCALAPPDATA\ssh-protocol-handler.reg"
[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
Invoke-WebRequest -Uri $url -OutFile $file
(Get-Content -path $file -Raw) -replace '<LOCALAPPDATA>', "$( [regex]::escape($env:LOCALAPPDATA) )"| Set-Content -Path $file
get-Content $file
reg import $file
rm $file

If you download the script manually, replace <LOCALAPPDATA> by the path where you stored ssh-protocol-handler.ps1

Step4: Activate the new handler

Open the windows settings. Go to "Apps & feature -> Default Apps", scroll down and click on "Choose default apps by protocol".

Now type in an SSH Url into the URL bar of any browser, for example ssh://user@example.com:2222. A PowerShell windows should open trying to connect you.

Create users and user groups

From the user administration, you can create new users and user groups. A new group is created by typing in the group name while creating or updating a user. A new user group comes without any permissions.

Assign clients to users

By default, a user who's not a member of the Administrators group can't do anything with rport. From the inventory, you can assign a host to none-admin users. This enables the users to execute any action on the host.

Starting with RPort version 0.9.0 assigning a client to a user will not give only minimal rights such as searching for clients and viewing their inventory. For any further action like creating tunnels or executing scripts, group permission is needed.

Assign permissions to user groups

RPort version 0.9.0 has introduced user group permissions. To allow certain actions, you must give permission to a user group.

If two or more groups are assigned to a user and groups have contra dictionary permissions, the authorization wins over the denial.

Example: If a user is a member of the groups Red and Blue, and Red allows script while Blue denies it, script will be allowed.

Keep in mind, that client permission is also needed. If a user is a member of a group with scripts unlocked, the user can execute scripts only on the assigned clients.

Starting with RPort version 1.0.0 extended user group permissions are enabled always, and they can't be turned off. That means, enabling tunnels or commands permissions for a user group provides optional configuration on the tunnels or command tab. Checking the tunnels or commands check box on the base tab will give unrestricted permissions to tunnels or commands because the default permissions for both are to allow everything.

Commands permissions

Having the command's checkbox enabled will enable command execution for the user group. By default, all commands are allowed. By enabling the toggle, fine-grained command permissions can be set up for a user group.

The Allow and Deny-List consists of regular expressions. Deny rules are checked first. If the deny rules are empty, any command that matches the allow rule will be allowed.

The below example means:

1. The user group can execute the exact command sudo reboot.

2. The group can restart any service.

3. The group can execute any command that contains the keyword hostname.

4. Executing systemctl ssh restart will be denied because the deny rule matches first.

Tunnels permissions

Having the tunnels checkbox enabled will enable tunnel creation. By default, all tunnels are allowed. Optionally, you can create advanced rules that apply to the tunnel creation. Navigate to the Tunnels tab and enable the toggle. Any value that you enter will become a mandatory setting for the user group when trying to create a tunnel.

Not filling one of the input fields means not restrictions apply. E.g., if you leave “Bind port on the rport server …” blank, the user group is allowed to create tunnels using any port.

With the settings shown in the below example, the user group is only allowed to create tunnels for RDP and SSH on the TCP ports 22 and 3389. Any other tunnel that's not matching these rules will be refused.

Before installing RPort Server, take five minutes to watch this video. Good preparation will save you a lot of time later.

The video covers

In this video you will get a recommendation for the best practises so that you can test RPort quickly and easily.

• We will compare a cloud installation with an on-premises installation.

• There will also be a discussion of the pros and cons of server installation on a dedicated virtual machine versus installation on a general purpose server.

• In addition, we will take a look at the disadvantages of a Docker installation.

• And finally, we are going to say a few words about reverse proxies.

The video covers

The video shows how to install the R-Port server on a fresh virtual machine dedicated to running only the R-Port server.

The virtual machine needs a direct connection to the Internet via its own public IP address.

For installation on servers behind network address translation, please see the dedicated video.

This tutorial is suitable for a server installation on

• Amazon web service (AWS)

• Google Compute (GCP)

• Hetzner Cloud

• Vultr

• Digital Ocean

• Mircosoft Azure

• any other cloud provider

• any VM or bare metal server with its won public IP address

Prerequisites

Copying files to a remote system over scp or sftp requires an SSH server running on the remote side. On almost all Linux systems SSH is installed and active.

Create a tunnel for SSH access to the remote server. The tunnel will end on a random port on your rport server. Remember the port number.

Using scp or rsync

To copy a file to the remote system over the tunnel via scp use

scp -P <PORT> <LOCAL-FILE> <USER>@<RPORT-SERVER>:<DESTINATION>

For example:

scp -P 22708 /etc/hosts hero@rport.example.com:/tmp/

Doing the same over rsync

rsync -e "ssh -p 22708" /etc/hosts hero@rport.example.com:/tmp/

Using Filezilla

• Open the site manager of Filezilla.

• Create a new site using the "SFTP- SSH File Transfer Protocol.

• Enter the name of the rport server as "Host".

• Enter the port of the tunnel as port for the Filezilla connection

The video covers

In this video, I’ll show you how to install the rport server on a virtual machine that is behind network address translation. The goal of the installation is to make the web interface available securely over the Internet using HTTPS. In addition, all your remote machines will be able to connect to the RPort server from anywhere. The video covers the server installation and the necessary router changes.

Commands used in this video

Install netcat on Ubuntu.

apt install netcat-openbsd

Start a simple TCP server on a given port.

nc -l <PORT>

Make a test connection to a host on a given port

Test-NetConnection -ComputerName <HOSTNAME> -Port <PORT>

Download the server installation script.

curl -o rportd-installer.sh
bash rportd-installer.sh -h

Download and import the RPort certificate authority.

iwr "https://<RPORT-SERVER-IP>:<PORT>/rport-ca.crt" -SkipCertificateCheck `
  -OutFile rport-ca.crt  
Import-Certificate -FilePath rport-ca.crt `
  -CertStoreLocation 'Cert:\CurrentUser\Root' -verbose

Find examples for Linux and macOS here.

This video will show you how to connect your remote devices to the R-Port server.

Inspect the log file

If your server doesn't start, look at the main server log file /var/log/rport/rportd.log first. This can be done with a text editor or with the tail command. For example, tail -n 200 /var/log/rport/rportd.log shows the last 200 lines.

Sometimes critical errors occur before the rport server can write log to its log file. These errors are usually logged through systemd. Use journalctl -u rportd.service -e --no-pager to inspect them.

If the above doesn't provide you enough information to understand why your server is not starting, try to run rportd without systemd in the foreground, which will print errors directly on your console.

# Run rportd in foreground
su - rport -s /bin/bash -c "/usr/local/bin/rportd -c /etc/rport/rportd.conf"

Share diagnostic data with the support

If you want to share diagnostic data with the RealVNC support, add the relevant files to an encrypted ZIP file and upload for later download.

# Share diagnostic data
journalctl -u rportd.service -e --no-pager > /tmp/rportd.journal.log
zip -r -e /tmp/rportd-diagnostic.zip /tmp/rportd.journal.log /etc/rport/ /var/log/rport/
curl --upload-file /tmp/rportd-diagnostic.zip https://transfer.sh/rportd-diagnostic.zip

The above command will ask for an encryption password. Provide a secure password and confirm. After the upload is completed, a download URL staring with https://transfer.sh is printed on the console. Share this URL and the password with the support engineer.

In this video, you will learn how to use rport remote access for Linux and Windows systems.

This video covers

• First, remote access to a Windows PC using the local remote desktop client.

• Second, remote access to a Linux system.

• Third, remote access to Windows using the built-in browser-based remote desktop client.

• And in the fourth example, you will learn how to use a tunnel with any application, demonstrated with an FTP client accessing a remote filesystem over SSH.

In this video, we’ll look at all the components of rport and how they communicate with each other.

The video covers

• What ports are used for what?

• What needs to be allowed on your firewall?

• How does remote access over tunnels work?

• What port forwarding do you need if you are using a router with Network Address Translation?

We will start with an RPort server with a directly attached public IP address.

In the second part, I’ll explain how the setup changes if you run the rport server behind network address translation, where the public IP address is bound to the router.

Problem

You want to restart the rport client, but you are connected via a tunnel (RDP, VNC or SSH). If you just execute a restart command, you will kill the current connection and the restart is also killed halfway. The client will not reconnect.

Solution

You must restart the client with a small delay from a background process. This is done best from the rport script interface.

On Linux

On Linux, execute the following script:

if [ "$(id -u)" -ne 0 ];then 
    echo "Not root. Please enable sudo";
    exit 1
fi
if which at >/dev/null 2>&1; then
    echo "$RESTART_CMD" | at now +1 minute
    echo "Restart of rport scheduled via atd."
else
    nohup sh -c "sleep 10;$RESTART_CMD" >/dev/null 2>&1 &
    echo "Restart of rport scheduled via nohup+sleep."
fi

Make sure, you enable sudo.

On Windows

On Windows, a few more lines of PowerShell are required to execute a task in the background. Execute the following script to safely restart rport.

function Invoke-Later {
    Param
    (
        [Parameter(Mandatory = $true)]
        [string] $ScriptBlock,
        [Parameter(Mandatory = $false)]
        [int] $Delay = 10,
        [Parameter(Mandatory = $false)]
        [string] $Description = "Background Task"
    )
    $taskName = 'Invoke-Later-' + (Get-Random)
    $taskFile = [System.Environment]::GetEnvironmentVariable('TEMP', 'Machine') + '\' + $taskName + '.ps1'
    $ScriptBlock.Split("`n") | ForEach-Object {
        if ($_)
        {
            $_.Trim() | Out-File -FilePath $taskFile -Append
        }
    }
    "Unregister-ScheduledTask -Taskname $( $taskName ) -Confirm:`$false" | Out-File -FilePath $taskFile -Append
    "Remove-Item `"$( $taskFile )`" -Force" | Out-File -FilePath $taskFile -Append
    $action = New-ScheduledTaskAction -Execute "powershell" -Argument "-ExecutionPolicy bypass -file $( $taskFile )"
    $trigger = New-ScheduledTaskTrigger -Once -At (Get-Date).AddSeconds($Delay)
    $principal = New-ScheduledTaskPrincipal -UserID "NT AUTHORITY\SYSTEM" -LogonType ServiceAccount -RunLevel Highest
    $settings = New-ScheduledTaskSettingsSet -AllowStartIfOnBatteries
    $task = New-ScheduledTask -Action $action -Principal $principal -Trigger $trigger -Settings $settings
    Register-ScheduledTask $taskName -InputObject $task
    Write-Output "* Task `"$( $Description )`" [$( $taskFile )] scheduled."
    Write-Output "  It will be executed within $( $Delay ) seconds."
}
Invoke-Later -Description "Restart RPort" -Delay 10 -ScriptBlock {
    Stop-Service rport
    Start-Service rport
}

Make sure you execute the script with PowerShell.

• Preparation before installing the RPort server, 🎦 Start Video

• RPort Server installation on premises, 🎦 Start Video

• RPort Server installation on cloud, 🎦 Start Video

• RPort Client installation, 🎦 Start Video

• Remote access to Windows and Linux systems, 🎦 Start Video

• RPort network communication explained, 🎦 Start Video

What is the "id" and why must it be unique?

All clients are identified by an id. During the client installation, the id is written to the rport.conf file. This id can be any string. Operating system create a worldwide unique id for each system during the installation process.

The rport pairing script takes the id of the operating system and inserts it to the rport.conf file.

On Linux the id is taken from /etc/machine-id or a hash of all mac addresses is created, if the machine-id file is missing.

On Windows the computer system UUID is used. Get-CimInstance -Class Win32_ComputerSystemProduct).UUID

Re-using existing identifiers creates a consistent view of your inventory. But you can use other identifiers if you want.

What causes duplicate ids?

Duplicate ids are almost always caused by system cloning. Either you have cloned a system with the rport client already installed, or after cloning, you have not created a new machine-id.

You will get an error like the below in the rport.log.

client: Connection error: client id "1234abc" is already in use

☝️ The problem is largely limited to Linux because Windows identifies it has been cloned, and a new UUID is created automatically.

How to solve the issue?

😬 Quick and dirty

You can edit the rport.conf with an editor and insert a randomly created UUID. Restart the client and it will connect flawlessly.

🧡 Properly

Having systems with duplicate machine-ids on a local network is not a good idea. It can cause other issues. First reset the machine id of the operating system, reboot and copy the new id from /etc/machine-id and insert it into the rport.conf.

📖 Reset machine id on Ubuntu 📖 Reset machine id on Debian 📖 Reset machine id on RHEL, CentOS, Rocky etc.

RPort 0.9.12 and newer

RPort 0.9.12 has introduced a command line interface to set password of existing users.

Log in via SSH to your RPort server. Switch to the rport user account by executing su - rport -s /bin/bash. 🙅‍♂️ Do not perform the next steps from the root user account!

To change a password of a user, execute:

rportd user change -u <USERNAME> -p -c /etc/rport/rportd.conf

You will be asked interactively for the new password.

RPort 0.9.5 and older

Step 1 – log in via SSH

To reset a lost password, login to your RPort server via SSH and become the root user. If you have installed the RPort server with the cloud-installer script, a sqlite3 database is used for authentication.

If you are not sure what is the underlying storage for users and passwords, open the configuration file with a page, for example, less /etc/rport/rportd.conf and scroll down to the [api] section.

Step 2 – create a new hash

If you are using a static pair of username and password – option number 1 in the above screenshot – just change it and restart the rport server.

If users and passwords are stored in a json-file or in a database, all passwords are stored as brypt hashes. Create a new hash and store it in the variable PASSWD_HASH.

NEW_PASSWD="<TYPE_IN_HERE>"
PASSWD_HASH=$(htpasswd -nbB password $NEW_PASSWD|cut -d: -f2)

Step 3 – update the password

On a json file

If you are using a json file, open it with a text editor, go to the line of the user you want the password to be updates, and replace the password hash by the one previously created.

Restart the rport server using systemctl restart rport and you are done.

On a sqlite database

Check who is in there.

DB_FILE=/var/lib/rport/user-auth.db
cat <<EOF|sqlite3 $DB_FILE
.headers ON
SELECT * FROM users;
EOF

Update the password hash of a user

DB_FILE=/var/lib/rport/user-auth.db
cat <<EOF|sqlite3 $DB_FILE
UPDATE users SET password="$PASSWD_HASH" WHERE username="admin";
EOF

This will update the password of the user admin with the previously created hash. 💪 You are done. You don't need to restart the rport server.

Preface

You can execute scripts on a per-client basis directly on the clients page. By selecting "scripts" on top navigation, you can execute scripts on many clients in parallel.

On Windows

Learn, from this video, how to execute PowerShell scripts on Windows machines (servers or desktop) – on a single machine and on multiple targets in parallel.

The video show how to install 7zip and notepad++ fully unattended with RPport using the following lines of PowerShell.

iwr https://7-zip.org/a/7z1900-x64.msi -OutFile 7z1900-x64.msi
msiexec /i 7z1900-x64.msi /quiet /qn /norestart
sleep 10
Remove-Item -Path 7z1900-x64.msi -Force
if (Test-Path "C:\Program Files\7-Zip\7z.exe") {
    Write-Host "7zip installed"
}

if (Test-Path "C:\Program Files\Notepad++\notepad++.exe" -PathType leaf) {
    Write-Host "Notepad++ is already installed."
} 
else {
    cd $env:Temp
    iwr https://notepad-plus-plus.org/repository/7.x/7.0/npp.7.Installer.x64.exe -OutFile npp.7.Installer.x64.exe
    .\npp.7.Installer.x64.exe /S
    sleep 10
    rm npp.7.Installer.x64.exe -Force
    New-Item -ItemType SymbolicLink -Path "C:\Users\Public\Desktop\" -Name "notepad++.lnk" -Value "C:\Program Files\Notepad++\notepad++.exe"
    Write-Host "Notepad++ installed"
}

On Linux

Type in the content of a script. You can use a regular shebang as first line like #!/bin/bash or #!/usr/bin/env python3.

Custom script interpreters

Starting with version 0.6.0 you can execute your scripts with an interpreter.

Either enter the full path to the interpreter, or register available interpreters in the client's rport.conf file.

To register a script interpreter on the rport.conf file on the client and append a list of available interpreters. After restarting the client, they get available on the user interface.

Preparation

For a mass deployment of clients, where each client shall use its own client_id and password, proceed as follows:

1. Generate an API key with scope clients-auth.

2. Go to client access and generate a pairing script for any of the clients.

3. Download the bash or PowerShell script to your desktop, but don't execute it.

4. Open the scripts with an editor and go to the line where variables CLIENT_ID / $client_id and PASSWORD / $password are defined.

5. Delete the lines and replace with the below snippets. Each time you execute the script, new client credentials are created via an API call.

6. Now copy this script to new clients and execute.

Generate client credentials on Windows with PowerShell

#
# Create new client credentials
#
$apiToken = "xxxxx_b4306692-389c-4f4b-8c3c-50638ef07086" # Use token with 'clients-auth' scope
$apiUrl = "https://rport.example.com:443/api/v1/clients-auth"
$apiUser = "john"

$password = (-join ((48..57) + (97..122) | Get-Random -Count 14 | % {[char]$_}))
$client_id = $env:computername
$body = @{
    id=$client_id
    password=$password
}
$json = $body|ConvertTo-Json
$base64AuthInfo = [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes(("{0}:{1}" -f $apiUser,$apiToken)))
Invoke-RestMethod -Uri $apiUrl -Headers @{Authorization = "Basic $base64AuthInfo"} -Method Post -Body $json -ContentType 'application/json'

Generate client credentials on Linux with bash

API_TOKEN="xxxxx_8fdef130-6597-4522-ae67-62feabfcf05d"
API_USER="john"
API_URL="https://rport.example.com:443/api/v1/clients-auth"

PASSWORD=$(openssl rand -hex 10)
CLIENT_ID=$(hostname -f)  # or use /etc/machine-id
BODY="{
    \"id\":\"${CLIENT_ID}\",
    \"password\":\"${PASSWORD}\"
}"
curl -fsu ${API_USER}:${API_TOKEN} ${API_URL} -H "Content-Type: application/json" -d "${BODY}"

Check the connection

Grab the address and port of your RPort sever.

Open the configuration file /etc/rport/rport.conf or C:\Program Files\rport\rport.conf with a text editor and look for the line that contains your RPort sever address. Or grab it directly from the console using grep "server =" /etc/rport/rport.conf on Linux or find "server =" "C:\Program Files\rport\rport.conf" on Windows.

The server settings consist of the FQDN or IP Address and the port, divided by colon. Optionally there is a protocol prefix http://.

Example: server = "v0e0vj4l5j1m.users.rport.io:80" The server address is v0e0vj4l5j1m.users.rport.io and the port is 80.

On Linux, execute echo > /dev/tcp/<SERVER>/<PPORT> && echo "All good"||echo "Server not reachable".

echo > /dev/tcp/v0e0vj4l5j1m.users.rport.io/80 && echo "All good"||echo "Server not reachable"
-bash: connect: No route to host
-bash: /dev/tcp/v0e0vj4l5j1m.users.rport.io/80: No route to host
Server not reachable

On Windows, use the PowerShell and execute Test-NetConnection -ComputerName <SERVER> -Port <PORT>.

If the above check fails, a firewall is blocking the outgoing connections.

Observe the logs

If the client is not connecting, you should look at the logs.

From a Windows PowerShell execute Get-Content "C:\Program Files\rport\rport.log"| Select-Object -Last 100.

From a Linux console execute tail -n 100 /var/log/rport/rport.log.

You might get a hint why the client is not connecting.

Check for transparent proxies

Some networks have implemented a so-called transparent proxy. All outgoing connection targeting a remote port 80 are intercepted and redirected through an HTTP proxy. Usually, this is done for automatic virus scanning or blockage of malicious websites. Because RPort uses encryption on application layer, a proxy cannot scan the packets send by the rport client. Most proxies deny the connection if they can't consider them as harmless.

How to solve such issues?

Create an exemption rule in the scanning engine of the proxy and exclude your rport server address from all scanning.

Use multiple ports for client connections

If the above is not possible, try using a different port than 80. If only a few clients are affected, do not change the client connections port of your RPort server. Just bring a second port that can be used as an alternative to the main port. The fastest way for doing this, is using rinetd. Install it by executing apt-get install rinetd, and create a config in /etc/rinetd.conf like the example below.

# Open port 8345 and forward to 80. 
# bindadress    bindport  connectaddress  connectport
0.0.0.0         8345      127.0.0.1       80 

Restart with service rinetd restart.

If you have numerous clients connecting through rinetd, you might get an error like socket(): Too many open files. On most distributions, the old system-v-inet is used to manage rinetd. Check systemctl status rinetd . If you get Loaded: loaded (/etc/init.d/rinetd; generated)the modern and de-facto standard, Systemd is not used.

Create a file /etc/systemd/system/rinetd.service with the following content:

[Unit]
Description=internet redirection server
After=network.target network-online.target
Requires=network-online.target

[Service]
User=root
Group=root
ExecStart=/usr/sbin/rinetd -f -c /etc/rinetd.conf
TimeoutStopSec=5s
LimitNOFILE=1048576
LimitNPROC=512
Restart=always
RestartSec=3

[Install]
WantedBy=multi-user.target

Pay attention to line 11 and 12. Now you have increased the limits to its maximum. To activate the new systemd service file, execute

systemctl daemon-reload
systemctl stop rinetd
systemctl start rinetd
systemctl status rinetd # should print "loaded /etc/systemd/system/rinetd.service"
systemctl enable rinetd

Problem

If you try to update labels are tags over the API or the user interface, you might get the “error client error: attributes file path not set”.

Updating attributes remotely requires that you enable this feature once in the rport.conf file on the client. This can't be done remotely.

Solution

Make sure the client runs rport version 0.9.12 or higher.

Log in to the client via SSH or Remote Desktop and open /etc/rport/rport.conf on Linux or C:\Program Files\rport\rport.conf on Windows with a text editor.

Inside the [client] section, insert or activate the following lines. Depending on the version, the lines are already present but disabled.

  ## A list of of tags and labels to give your clients attributes maintained in a separate file.
  ## See https://oss.rport.io/advanced/attributes/
  #attributes_file_path = "/var/lib/rport/client_attributes.json"
  #attributes_file_path = "C:\Program Files\rport\client_attributes.json"
  ## Alternatively you can specify tags with the line below if {attributes_file_path} is not set.
  #tags = ['win', 'server', 'vm']

Make sure one of the line starting with attributes_file_path is active (no hash sign # in front of it). Make sure the line starting with tags is disabled by putting a hash sign.

Restart the rport client after making the changes. Use service rport restart on Linux or restart-service on Windows.

How does RPort work?

Client-Server that overcomes NAT

RPort is based on a client-server principle. There is a central server. The clients connect to this server. This ensures that the server can always reach its clients, even if they change their IP address or are behind a NAT.

Encryption on application layer over HTTP

Clients establish their connection via HTTP. The use of HTTP proxies is supported. Within the HTTP connection, an SSH connection is established from the client to the server. Thus, the entire communication is encrypted. Proxies must allow HTTP CONNECT. Consequently, encryption happens at the application level and not at the transport level.

The client must know the fingerprint of the server before the connection is established. If the fingerprint does not match the server, the client refuses the connection. This prevents a possible man-in-the-middle attack.

The statically compiled client has all SSH libraries on board. It does not access SSH program files in the operating system.

RPort uses the SSH library GoSSH from Google. Only SSH2 is used with the standard ciphers aes128-ctr, aes192-ctr, aes256-ctr and aes128-gcm@openssh.com.

Authentication is not done with keys, but with username+password+fingerprint. The users determines the password strength.

Control Channel

Once the SSH connection tunnelled through HTTP is established, the client and server establish a so-called control channel based on web sockets. Through this channel, the server can send commands to the client. Whether and how the client passes commands to the operating system or a shell can be specified in great detail in the client configuration. For example, the user can only allow a service to be restarted or updates to be applied. Under Unix, this requires additional Sudo rules. The client has its own unprivileged user and does not run with root privileges.

Tunnelling for remote access from anywhere

If the user wants to access a TCP or UDP port of a client, for example port 22 for SSH or 3389 for the remote desktop, the server instructs the client to establish a reverse tunnel. This also happens via SSH through HTTP. This makes local ports of the clients available on the server. The ports forwarded in this way are protected by default with an access control list. Only the user who initiated the tunnel can use it. ACLs can be adjusted or disabled per tunnel. This allows services such as a web server to be shared on the Internet when systems are located behind NAT routers.

Tunnels are not limited to localhost. Any client can forward a remote TCP port to the server. This provides access to browser-based configurations of printers, NAS devices, routers, or switches.

Tunnels are not bound to a specific protocol on application level. RPort forwards raw TCP or UDP packets. On creation of a tunnel, you can optionally specify a protocol such as SSH or RDP etc. This information is just for convince to remind you, what the tunnel was created for. Once a tunnel is created, you can pass any application traffic through it.

RESTful API and a user interface based on modern vue.js

The RPort server is controlled via REST API. Since each client gets its own REST endpoint, the clients also become controllable via REST. This makes numerous automation use cases possible.

RPort also comes with a modern web interface. This allows the customer to conveniently manage their entire infrastructure.

Security notice

The execution of commands must be allowed in the rport client configuration file /etc/rport/rport.conf on Linux or C:\Program Files\rport\rport.conf on Windows.

You can create a list of allowed commands and a list of disallowed commands. This allows fine-grained filtering.

Multiple commands

It is possible to execute multiple commands. On Windows, you must concatenate the commands with a single ampersand &. On Linux, you can use line breaks or the semicolon.

Bear in mind that the concatenation signs &, ; , \n must be allowed by the regular expression on the command restrictions.

👺Pitfalls

If you only want to allow a limited set of commands, pay special attention to the deny rules. Look at the following example.

These rules are leading to an unrestricted command execution because systemctl (status|restart) can be followed by any character. For example, systemctl status cron;poweroff is possible. If you want to allow just single command but with parameters, you must deny all characters that allow command concatenation.

Windows PowerShell

Command are always executed on the cmd.exe shell of Windows. To execute a PowerShell command, you must prefix the command with powershell, for example, powershell "Get-Service spooler".

If you only want to allow restarting any service via PowerShell change your configuration as follows.

Get your API Token

To use the API, you must get your personal API token. A token belongs to a user, and all user-rights (or limits) are applied to each transaction executed with the token.

From the settings menu in the top-right corner, select "API Token". Generate a new token. The token is displayed only once. If you lose the token, it can't be recovered. So store the token in a safe place.

Test the token

The base URL of the API is https://<server-domain>/api/v1. You must use HTTP basic authentication using your username and the API token as password.

Test the API connection by fetching the server status. Example:

curl -u john:740df110-8b06-4071-90c1-13645a023a85 \
https://example.users.rport.io/api/v1/status

Full API documentation

You can read the API documentation online here.

Starting with RPort 0.7.0 a centralized cron-like scheduler has been introduced.

Prerequisites

Both, the server and the clients must run at least version 0.7.0 of Rport to use the scheduler. Updating all your clients is not necessary as long as you don't want to run scheduled scripts on them.

For a single client

Create a schedule

Click on the Commands or Scripts tab of a client. Enter the script or command that you want to execute. You can execute it right away to verify it's doing what is it supposed to do. To execute the command or script at a given time, click the gray Schedule button. Using cron syntax, you can then specify the execution interval. Cron syntax is used for Windows, Linux and macOS.

Supervise schedules

From the "Schedules" tab, you get access to the reports. You can verify the success of all schedules jobs.

For multiple clients

Create a schedule

Scheduling a script are command for multiple clients works similar to executing scripts are commands. Click on the global Command or Scripts icon on the main menu on the left side.

Select on which clients a script or command should be executed. Instead of executing right away, klick on Schedule.

Supervise schedules

Using the global Schedules section accessed from the main menu on the left side, you can supervise all schedules. Those created for a single client and those created for multiple clients.

Built-in and optional security measures

• Transport Layer Security (TLS): RPort utilizes TLS encryption to secure all communication between the server and managed devices. TLS encrypts data in transit, preventing eavesdropping and data tampering. The administrator can enforce the usage of TLS 1.2 or 1.3.

• SSH Tunneling: For remote access to devices, RPort employs SSH tunneling, which encrypts remote connections within an existing SSH session. This further enhances security by encapsulating RPort's traffic within a trusted SSH channel.

• Two-Factor Authentication (2FA): RPort mandates 2FA for all administrative access, adding an extra layer of security beyond passwords. 2FA requires an additional verification factor, such as a code from a mobile app, making it virtually impossible to compromise accounts with stolen passwords.

• Access Control Lists (ACLs): RPort implements granular access control policies based on user roles and device permissions. This restricts access to specific devices and functions, preventing unauthorized actions.

• Vulnerability Scanning and Patch Management: RPort can regularly scan managed devices for known vulnerabilities and promptly deploys recommended security patches to minimize the risk of exploitation. Required scripts and actions are not included and must be developed by the user.

• Malware Detection and Prevention: Optionally, RPort can integrate with anti-malware solutions to detect and block malware infections, protecting devices from malicious software. Required scripts and actions are not included and must be developed by the user.

• Secure Remote Desktop (RDP): RPort utilizes secure RDP sessions to connect to remote Windows devices, ensuring that all data transmitted during these sessions remains encrypted.

• Virtual Network Computing (VNC): RPort employs secure VNC sessions using RealVNC's latest frame buffer protocol with AES256 encryption, which provide remote access with encryption and authentication.

Secure development and software lifecycle guided by Mend

The RPort software development is strictly supervised by Mend. Mend, formerly WhiteSource, is a comprehensive software composition analysis (SCA) platform that helps RPort to identify, prioritize, and fix vulnerabilities in their software applications. By scanning code, binaries, and container images, Mend detects known security vulnerabilities, license compliance issues, and potential security risks early in the development lifecycle.

Mend's scanning capabilities improve the security of RPort in several key ways:

1. Early Detection of Vulnerabilities: Mend's scans identify vulnerabilities in code and dependencies early in the development process, before they are deployed to production. This allows developers to fix vulnerabilities quickly and easily, reducing the risk of security breaches.

2. Improved Developer Productivity: By shifting security left, Mend helps RPort to integrate security into the development process, making it mandatory for developers to write secure code. This reduces the time and effort required to remediate vulnerabilities later in the development lifecycle.

3. Automated Remediation: Mend automatically generates patches for many vulnerabilities, making it easy for developers to fix them without manually searching for and applying patches. This saves time and effort, and it helps to ensure that vulnerabilities are fixed promptly.

4. Reduced Risk of Security Breaches: By identifying and fixing vulnerabilities early, Mend reduces the risk of security breaches. This protects sensitive data and protects the reputation of the organization.

5. Compliance with Regulations: Mend complies with various software security and licensing regulations, such as the Payment Card Industry Data Security Standard (PCI DSS) and the General Data Protection Regulation (GDPR).

The difference between commands and scripts

The command’s tab is indented to be used to execute a single command. Entering multiple commands is possible, but if you want to implement complex logic, it's better to use a script.

Why not use scripts always? Security is the reason.

Both command and script execution must explicitly be allowed in the rport client configuration. For the commands, you can create a list of allowed commands and a list of disallowed commands. This fine-grained filtering is not possible with scripts.

[remote-commands]
  ## Enable or disable execution of remote commands sent by server.
  ## Defaults: true
  #enabled = true

  ## Allow commands matching the following regular expressions.
  ## The filter is applied to the command sent. Full path must be used.
  ## See {order} parameter for more details how it's applied together with {deny}.
  ## Defaults: ['^/usr/bin/.*','^/usr/local/bin/.*','^C:\\Windows\\System32\\.*']
  #allow = ['^/usr/bin/.*','^/usr/local/bin/.*','^C:\\Windows\\System32\\.*']

See all configuration options and more configuration examples.

If you feel it were better not to give full control over the clients to the RPort server, you should script execution of.

[remote-scripts]
  ## Enable or disable execution of remote scripts sent by server.
  ## Defaults: false
  #enabled = false

The restrictions for command and scripts always apply regardless of whether it's executed for a single client or many clients concurrently.

Single run vs. concurrency

Both – command and scripts – can be executed on a single client or on many clients in parallel. Selecting a client on the left side gives you access to the command or scripts tab for a single client.

Selecting commands or scripts on the top navigation gives you access to the parallel execution.

On Linux

To remove the RPort client and all logs and the configuration, execute the following command.

curl https://pairing.rport.io/update -o rport-update.sh 
sudo sh rport-update.sh -u

On Windows

The RPort installer has created an uninstaller. Go to C:\Program Files\rport and execute uninstall.bat.

To remove it manually, open a cmd shell, go to C:\Program Files\rport and execute

sc stop rport
rport.exe --service uninstall

Delete the folder C:\Program Files\rport

Command execution

Enabling script and command execution is not global and it is not an either/or decision. You can control which commands are allowed and which are not on a fine-grained level. See the example below.

[remote-commands]
  ## Enable or disable execution of remote commands sent by server.
  ## Defaults: true
  #enabled = true

  ## Limit the maximum length of the command output that is sent back to server.
  ## Applies to the stdout and stderr separately.
  ## If exceeded {send_back_limit} bytes are sent.
  ## Defaults: 2048
  #send_back_limit = 2048

  ## Allow commands matching the following regular expressions.
  ## The filter is applied to the command sent. Full path must be used.
  ## See {order} parameter for more details how it's applied together with {deny}.
  ## Defaults: ['^/usr/bin/.*','^/usr/local/bin/.*','^C:\\Windows\\System32\\.*']
  #allow = ['^/usr/bin/.*','^/usr/local/bin/.*','^C:\\Windows\\System32\\.*']

  ## Deny commands matching one of the following regular expressions.
  ## The filter is applied to the command sent. Full path must be used.
  ## See {order} parameter for more details how it's applied together with {allow}.
  ## With the below default filter only single commands are allowed.
  ## Defaults: ['(\||<|>|;|,|\n|&)']
  #deny = ['(\||<|>|;|,|\n|&)']

  ## Order: ['allow','deny'] or ['deny','allow']. Order of which filter is applied first.
  ## Defaults: ['allow','deny']
  ##
  ## order: ['allow','deny']
  ## First, all allow directives are evaluated; at least one must match, or the command is rejected.
  ## Next, all deny directives are evaluated. If any matches, the command is rejected.
  ## Last, any commands which do not match an allow or a deny directive are denied by default.
  ## Example:
  ## allow: ['^/usr/bin/.*']
  ## deny: ['^/usr/bin/zip']
  ## All commands in /usr/bin except '/usr/bin/zip' can be executed. Full path must be used.
  ##
  ## order: ['deny','allow']
  ## First, all deny directives are evaluated; if any match,
  ## the command is denied UNLESS it also matches an allow directive.
  ## Any command which do not match any allow or deny directives are permitted.
  ## Example:
  ## deny: ['.*']
  ## allow: ['zip$']
  ## All commands are denied except those ending in zip.
  ##
  #order = ['allow','deny']

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 from https://downloads.rport.io 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.

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.

At a glance

Tacoscript is a declarative scripting language for the easy automation of tasks. It uses human-readable YAML as input files. The interpreter consists of a single static binary available for almost any operating system. Read more.

Install Tacoscript

Only for Rport versions before 0.5.0 tacoscript is not installed by default. You must install it manually. But you can use the RPort script execution to perform the installation from the RPort web interface.

$dest = "C:\Program Files\tacoscript"
if(Test-Path -Path $dest) {
    Write-Host "Tacoscript already installed to $($dest)"
    exit 0
}
$Temp = [System.Environment]::GetEnvironmentVariable('TEMP','Machine')
Set-Location $Temp
$url = "https://download.rport.io/tacoscript/stable/?arch=Windows_x86_64"
$file = "tacoscript.zip"
[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
Invoke-WebRequest -Uri $url -OutFile $file -UseBasicParsing
Write-Host "Tacoscript dowloaded to $($Temp)\$($file)"
New-Item -ItemType Directory -Force -Path "$($dest)\bin"|Out-Null
Expand-Archive -Path $file -DestinationPath $dest -force
mv "$($dest)\tacoscript.exe" "$($dest)\bin"
Write-Host "Tacoscript installed to $($dest)"
$ENV:PATH="$ENV:PATH;$($dest)\bin"

[Environment]::SetEnvironmentVariable(
        "Path",
        [Environment]::GetEnvironmentVariable("Path", [EnvironmentVariableTarget]::Machine) + ";$($dest)\bin",
        [EnvironmentVariableTarget]::Machine
)
& tacoscript --version
rm $file -force

#!/bin/sh
#
# Install Tacoscript on Linux
#
set -e
if [ -e /usr/local/bin/tacoscript ];then
   echo "Tacoscript already installed"
   exit 0
fi
cd /tmp
test -e tacoscript.tar.gz&&rm -f tacoscript.tar.gz
curl -LJs "https://download.rport.io/tacoscript/unstable/?arch=Linux_$(uname -m)" -o tacoscript.tar.gz
tar xvzf tacoscript.tar.gz -C /usr/local/bin/ tacoscript
rm -f tacoscript.tar.gz
tacoscript --version

Enable Update supervision

On Linux

To enable update supervision you must have the following line in the [client] section of your /etc/rport/rport.conf file.

[client]
 # ...snip ...snap
 updates_interval = '4h'

A refresh of the update status can be requested through the API and the user interface independently of the specified update interval. Going faster than 4 hours is usually not need and not recommended.

⚠️ Debian, Ubuntu and SuSE Linux need a sudo rule to fetch the update status. Create a file /etc/sudoers.d/rport-update-status with the following content.

rport ALL=NOPASSWD: SETENV: /usr/bin/apt-get update -o Debug\:\:NoLocking=true

rport ALL=NOPASSWD: SETENV: /usr/bin/zypper refresh *

Starting with version 0.7.0 it's possible to upload files directly to remote clients and store them anywhere on the remote file system.

Prerequisites

Both, the server and the clients must run at least version 0.7.0 of Rport to use the file copy function. Updating all your clients is not necessary as long as you don't want to use this feature on them.

Pay attention to the optional filters that can be used to exclude folders from write access. By default, files cannot be coped to most OS-critical folders. Extend the filters according to your needs.

[file-reception]
  ## Receive files pushed by the server, enabled by default
  # enabled = true
  ## The rport client will reject writing files to any of the following folders and its subfolders.
  ## https://oss.rport.io/docs/no18-file-upload.html
  ## Wildcards (glob) are supported.
  ## Linux defaults
  # protected = ['/bin', '/sbin', '/boot', '/usr/bin', '/usr/sbin', '/dev', '/lib*', '/run']
  ## Windows defaults
  # protected = ['C:\Windows\', 'C:\ProgramData']

🕵 On Linux, a sudo rules is needed and created by default to allow changing the owner and mode of a file. Review and/or delete /etc/sudoers.d/rport-filereception if it conflicts with your security policies.

Transfer files

• Once a client allows file reception, click on the Files tab.

• Select a local file.

• Specify where the file should be store remotely. 👉 You must enter a full path, not a folder.

• On Linux, you can also specify the owner and mode of the file.

The more clients you manage with RPort the more important it is to constantly monitor the faultless operation of the server. You must get notified quickly if errors occur.

If you have a monitoring solution in place, integrate your rport server there. If you run the rport server on a cloud service like AWS or Azure, you can use their monitoring.

A basic monitoring should supervise:

1. The uptime of the server itself (ICMP Ping)

2. Check if the port for the clients connections, 80 by default, is up.

3. Check if the port of the API/UI, 443 is up and certificates have not expired.

4. There is always enough disk space free on the server.

5. Your backups are executed constantly and flawlessly.

Use the free Better Uptime service