GITHUB

Install on-premises

Learn how to install the rport server inside your intranet on your own (virtual) server.

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.

Read first, then act. 📖 We kindly invite you to read this article entirely before installing. But if you are impatient, the following examples will also demonstrate the capabilities of the server installer.

Alternatively, read the help message of the installer script.

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

RPort open-source has been dicontinued 2023-09-20. The RPort installer and the server executable will require a valid license.

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 could 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
PreviousLaunch RPort in the cloudNextInstall on Vultr

Last updated