# OpenRPort Knowledge Base Learn how to use OpenRPort 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.** [Read more](https://2500109324-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fp4ON1axBW24W9NpMHB26%2Fuploads%2FVD9mS7mwVk1tNTvPAPpy%2Ffeatures%20and%20benefits%20of%20rport?alt=media) ​ # Features and benefits of RPort 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. Full and comprehensive overview of all your machines. Log in to any windows server via RDP from everwhere Log in to any Unix machine from everywhere through reverse tunnels. Execute Powershell scripts from the browser. Execute a command on many machines in parallel. Fast and easy pairing of new machines. Secure log in with two-factor authentication. # Full feature list ✌️ RPort makes your job a lot easier. This is a list of all available and upcoming features of RPort. **The current version** is `1.0.1` released 2023-09-25. * 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. * 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 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) * 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. * 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 🔖](https://github.com/cloudradar-monitoring/tacoscript) . * With the file copy function , you can copy local files from your PC directly to a remote machine. * The RPort database comes with an [encrypted table](about:/what-is-rport/features-and-benefits-of-rport/full-feature-list#vault) 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. #### 🌶️ Planned features for 2023 * Built-in file server with the capability to copy files from the RPort server to the clients and vice versa. *No release date yet.* * Support for clustered databases to set up a high available RPort server. *No release date yet.* * Mobile optimized UI version. *No release date yet.* * Customized branding. *No release date yet.* # Screenshots Get to know the software via screenshots Dashboard and inventory of a Linux client Linux client with SSH Tunnel Windows Client with RDP tunnel and Web RDP Inventory view across all clients Settings Bash-Script execution from the browser Powershell-Script execution from the browser Parallel script execution Encrypted metadata in the vault Pairing of a new client Windows client with an active RDP tunnel Auditlog Monitoring Create schedules Supervise schedules [PreviousFull feature list](https://2500109324-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fp4ON1axBW24W9NpMHB26%2Fuploads%2FvhTxzbFuC71IwZuYn2VE%2Ffull%20feature%20list?alt=media)[NextInstall the RPort Server](broken://pages/8TeBJTxL2Qt7woIlGljW) Last modified 9d ago # Install the RPort Server Use the fully automated installer to install the rport server in no time. Select where you want to install your RPort server. Usually it takes less than 5 minutes to get your RPort instance up and running. ⏱️ The more clients you manage, the more memory you need. You can roughly calculate \~430 KB per Client. 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) 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 need a long retention period, put large disks in your VM. #### Launch the RPort server in the cloud​ 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. #### Install the RPort server on-premises​ 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. # 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. Ports used in different scenarios (click to enlarge) #### 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.openrport.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). ``` $ curl -o rportd-installer.sh https://get.openrport.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 ` to use two-factor authentication with mobile apps like Google or Mircosoft authenticator.. **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. ```bash $ 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. * 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. 1\. **Client connection port**, `[server] address = ":"` 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 ` to install your rport server on a different port than 80. 2. 2\. **Client connection URL**, `[server] url = "http://:"`. 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://:"`. 3. 3\. **API & UI port,** `[api] address = ":"` 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 ` 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. 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 -` - 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](about:/install-the-rport-server/install-on-premises#import-the-root-certificate-authority-root-ca) . 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. Now it's time to let the magic happen. ``` $ curl -o rportd-installer.sh https://get.openrport.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. ``` 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-ca.crt`. The installer created a symbolic link, so the certificate is reachable via the built-in web server. 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-ca.crt" -SkipCertificateCheck ` -OutFile rport-ca.crt Import-Certificate -FilePath rport-ca.crt ` -CertStoreLocation 'Cert:\CurrentUser\Root' -verbose ``` **Import the certificate authority on Windows with PowerShell** ``` curl -LOsk "https://:/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-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-ca.crt" \ -o /usr/local/share/ca-certificates/rport-ca.crt sudo update-ca-certificates ``` # Install RPort on any virgin cloud VM Learn how to install the RPort server on any public cloud-based virtual machine. {% hint style="danger" %} The following guide assumes you are going to install the RPort server on a virgin virtual machine, running Debian or Ubuntu on a public cloud. **✋ Do not use this guide for installing RPort on servers inside an intranet where NAT (network address translation) is used.** To install RPort on a intranet host, follow this [guide](https://oss.rport.io/docs/#install-and-run-the-rport-server). {% endhint %} ### 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. ``` curl https://get.openrport.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. {% hint style="info" %} 💁 **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](broken://pages/-MfmnjR0jfug7TieDvGL). {% endhint %} {% hint style="success" %} You will be asked for your email address. **Your email address is required because two-factor authentication is enabled by default.** Tokens are sent via email. Your email address is stored only in the local database of your server. {% endhint %} 👉 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](broken://pages/-Met96iCzwGW3VjlQi7g) * 👉 [Test the remote access](broken://pages/-MetBQTzg0fsvGR7HyrS) * 👉 Perform regular backups # Enable two factor authentication Add an extra layer of security to your account ### 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. 3. Sending the token via the free **push service** [Pushover.net](https://pushover.net). (required an app on your mobile) 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. {% hint style="danger" %} Enabling 2FA and the method how token are sent, is a global setting. **You can not enable or disabel 2FA per user.** All users must use the same token delivery method. {% endhint %} * 👉 [Use push messages on mobile phones](broken://pages/-MfrU_EEdWRJbH99BGCr) for 2FA *(recommended)* * 👉 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. ⚠️ If you plan to use RPort permanently and in a productive environment, **stop using the free service**. It's highly recommended using either your own SMTP server or switching to [push messages](broken://pages/-MfrU_EEdWRJbH99BGCr). #### Privacy notes The free email service triggered by the script `/usr/local/bin/2fa-sender.sh` on your rport server submits the email and the token of the user over encrypted https to a web service operated by [cloudradar GmbH](https://www.cloudradar.io/imprint). Email addresses are not used for any other purpose than dispatching the two-factor token. Email addresses are not stored. #### 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. ```bash #!/bin/bash # /usr/local/bin/2fa-sender.sh # # This is a script for sending two factor auth token via a free API provided by cloudradar GmbH # Check https://kb.rport.io/install-the-rport-server/enable-two-factor-authentication # and learn how to use your own SMTP server or alternative delivery methods # RESPONSE=$(curl -Ss https://free-2fa-sender.rport.io \ -F email=${RPORT_2FA_SENDTO} \ -F token=${RPORT_2FA_TOKEN} \ -F ttl=${RPORT_2FA_TOKEN_TTL} \ -F url=https://dnpefye735n8.users.rport.io 2>&1) if echo $RESPONSE|grep -q "Message sent";then echo "Token sent via email" exit 0 else >&2 echo $RESPONSE exit 1 fi ``` In your `rportd.conf` insert the following lines to the `[api]` block. ``` two_fa_token_delivery = "/usr/local/bin/2fa-sender.sh" two_fa_send_to_type = "email" ``` # Use push on mobile for 2FA Use the Pushover app to receive one-time tokens ### Use push messages for 2FA RPort supports sending one-time tokens to mobile phones via [Pushover](https://pushover.net/). Pushover is a very tiny and versatile app available for [Android](https://pushover.net/clients/android) and [IOS](https://pushover.net/clients/ios). {% hint style="info" %} By creating a custom script you can send the token via any delivery method. This enables you to use Telegram or other messengers too. [Learn more](https://oss.rport.io/docs/no15-messaging.html#script) {% endhint %} 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 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. Enable message sending by creating an application Enter RPort as the name of the application and confirm the terms. A token is displayed. This is your sender token. Your token for sending messages 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= USER_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`. {% hint style="info" %} The user key is only used to verify the pushover connection on server start. No messages will be sent to this user key. User keys for sending the one-time token are configured per user. Entering the key of one user is harmless because the key doesn't provide access to the user account or any other personal data. {% endhint %} 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" ``` 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= cat < # Use TOTP Learn how to use any rfc6238 compliant token generator, e.g. Google or Microsoft authenticator 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: ``` ## To enable time-based onetime tokens generated by apps likes Google or Microsoft Authenticator, ## set 'totp_enabled = true'. ## Your user-password store (json files or DB table) needs an additional text field 'totp_secret'. totp_enabled = true ## Learn more on https://oss.rport.io/docs/no02-api-auth.html#two-factor-auth ## Before sending the token generated by the authenticator app, ## users should do a login attempt. Otherwise thye can request tokens directly without login. ## 'totp_login_session_ttl' sets the timeout after which totp codes won't be accepted totp_login_session_ttl = '600s' ## If you run multiple RPort servers, you should give them different totp account names ## to differentiate them on your authenticator app. totp_account_name = 'RPort' ``` 👉 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. # Connecting Clients Connect client for remote management ### Using the pairing service The fastest and easiest way to connect a new client with your RPort server instance is using the pairing service. 1. Click on the gears icon in the top-right corner. 2. Click on `Client Access`. 3. Select one of the credentials and on that row click on `Install Client`. 4. Copy the command snippet of the clients' operating system to the clipboard and paste it to a bash or PowerShell console of the machine you want to connect. 5. Click the refresh icon on top of the client list. ### Connect a Windows machine to the RPort server 📽️ {% embed url="" %} Learn how to connect a Windows machine {% endembed %} ### Connect a Linux Machine to the RPort Server 📽️ {% embed url="" %} Learn how to connect a Linux Client {% endembed %} ### 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. {% hint style="warning" %} The client credentials **can be used multiple times**. Technically, it's possible to connect all client – even hundreds – with the same credentials. **From a security perspective,** **this is not advised**. {% endhint %} The communication is one-way. The server talks to the clients. Clients cannot dispatch any command or action to the server. And clients cannot communication 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. {% hint style="info" %} Client IDs and authentifcation IDs are different. Both can be changed idependently. {% endhint %} 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. ![client vs. authentication id](https://1142160776-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MekeI9EovpQqbUTQSdM%2Fuploads%2FFGu0TBBKRZkhKdl7ctBS%2Fimage.png?alt=media\&token=18780c68-fc4e-41ef-878d-ec5497678582) ### 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.openrport.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. {% hint style="success" %} **Is it secure?** 💬 Yes. The uploaded credentials are not stored to disk on the pairing server. They remain in memory for 10 minutes. No backups are performed. {% endhint %} ### 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 ``` Usage rport-installer.sh [OPTION(s)] Options: -h print this help message -f force, overwriting existing files and configurations -v print version -t use the latest unstable version (DANGEROUS!) -u uninstall the rport client and all configurations and logs -x enable unrestricted command execution in rport.conf -s create sudo rules to grant full root access to the rport user -a Use a different user account than 'rport'. Will be created if not present. ``` On Windows, type in `Get-Help .\install.ps1 -full` to read the help message. If you are asked if you want to update the entire PowerShell help database, answer "no". ``` PS C:\Users\Administrator\Documents> Get-Help .\install.ps1 -full NAME C:\Users\Administrator\Documents\install.ps1 SYNOPSIS Installs the rport clients and connects it to the server SYNTAX C:\Users\Administrator\Documents\install.ps1 [-x] [-t] [] DESCRIPTION This script will download the latest version of the rport client, create the configuration and connect to the server. You can change the configuration by editing C:\Program Files\rport\rport.conf Rport runs as a service with a local system account. PARAMETERS -x [] Enable the execution of scripts via rport. Required? false Position? named Default value False Accept pipeline input? false Accept wildcard characters? false -t [] Use the latest unstable development release. Dangerous! Required? false Position? named Default value False Accept pipeline input? false Accept wildcard characters? false This cmdlet supports the common parameters: Verbose, Debug, ErrorAction, ErrorVariable, WarningAction, WarningVariable, OutBuffer, PipelineVariable, and OutVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). INPUTS None. You cannot pipe objects. OUTPUTS System.String. Add-Extension returns success banner or a failure message. -------------------------- EXAMPLE 1 -------------------------- PS>powershell -ExecutionPolicy Bypass -File .\rport-installer.ps1 -x Install and connext with script execution enabled. -------------------------- EXAMPLE 2 -------------------------- PS>powershell -ExecutionPolicy Bypass -File .\rport-installer.ps1 Install and connect with script execution disabled. RELATED LINKS Online help: https://kb.openrport.io/connecting-clients#advanced-pairing-options ``` #### # Using the remote access Log in to any server from everywhere via SSH or Remote Desktop ### 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. {% hint style="info" %} RPort does not interfere with the regular log in process of the operating system. A valid user account on the remote machine is always needed. {% endhint %} ### What are those tunnels? # Creating tunnels Get access to any remote TCP port Get access to any remote TCP port 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. * 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. Tunnel to access the remote desktop of a Windows server. **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. Launch a tunnel from the browser. 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](https://remmina.org/) should open. If not, make Remmina the default application for `*.rdp` files. 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 [email protected]`. 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. ​ 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. List of stored service forwardings. #### 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. ❗*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. Use the built-in HTTP Reverse Proxy **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. Tunnel with proxy in action #### 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](https://2500109324-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fp4ON1axBW24W9NpMHB26%2Fuploads%2FadtIAQvBcDPXs7s5B36J%2Fvnc%20via%20browser?alt=media) ​ # VNC via browser Use the browser for VNC connections 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. VNC connection from the browser #### 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. The VNC server must allow loop back connections. #### 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. Encryption settings of RealVNC Server for NoVNC 1.4.0 compatibility To access a RealVNC Server from the browser, select `VNC` as tunnel type, not `RealVNC`, and `Enable NoVNC (VNC via Browser)`. Browser-based access to a RealVNC server. VNC Viewer and the Rport URL integration is required for Multifactor authentication, High-Speed Streaming, Audio and connecting to Virtual mode/Virtual Mode Daemon. **VNC® Server from RealVNC®** should ony be used for RPort's browser-based VNC remote access if the RPort Server has noVNC 1.4.0 included. Older versions of NoVNC only supports old (open source) versions of the RFB protocol. RealVNC® has added a number of enhancements to the RFB protocol including encryption and additional authentication mechanisms not supported by NoVNC. ⛔ **It is not recommended to make any configuration changes to VNC® Server from RealVNC®** to achieve NoVNC 1.3.0 compatibility, like disabling security, using “VNC Password” authentication and setting protocol version to 3.8. 👉 Using the RPort/VNC® Viewer from RealVNC® integration is recommended. [Learn more](broken://pages/CISRpFP3Uf8UwYR1u7Ra) . # RDP via Browser Use the browser to access the remote desktop 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. Remote Desktop in the browser {% hint style="info" %} Sensitive data such as username and password are always transferred encrypted and directly passed through to the remote systems. No data is stored on the RPort server, not even temporary. {% endhint %} If you have upgraded your RPort server from an older version, you might need to install the Guacamole proxy manually. We provide tiny Debian/Ubuntu packages for fast and easy resolving of the dependency. [Read more](https://oss.rport.io/docs/no19-rdp-proxy.html) . # Open SSH from the browser Learn how to open SSH connections directly from the browser #### SSH Link handler for Windows RPort and your browser will open links to `ssh://[email protected]` with the default application for that URL scheme. Windows does not have any default application assigned. To do so, follow the guide below. 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 infos [here](https://docs.microsoft.com/de-de/windows-server/administration/openssh/openssh_install_firstuse#:~:text=OpenSSH%20client%20and%20server%20are,and%20Features%20%3E%20Manage%20Optional%20Features.) **Step 2: Download the wrapper script** An ssh link follows this syntax, `ssh://@:` 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://[email protected]: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. {% hint style="info" %} On desktop operation systems like Windows 10 and 11 the PowerShell execution policy is very likely set to "restricted". This will prevent the script to run. On a new PowerShell console *with administrative* rights change the policy to allow all local scripts and only those remote scripts that are digitally signed, by executing: `set-executionpolicy remotesigned` {% endhint %} **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 '', "$( [regex]::escape($env:LOCALAPPDATA) )"| Set-Content -Path $file get-Content $file reg import $file rm $file ``` If you download the script manually, replace `` by the path where you stored `ssh-protocol-handler.ps1` {% hint style="info" %} **Log out now.** Otherwise changes are not applied. {% endhint %} **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". Select the Custom SSH Handler Now type in an SSH Url into the URL bar of any browser, for example `ssh://[email protected]:2222`. A PowerShell windows should open trying to connect you. # Scp,sftp through a tunnel Learn how to copy files through a tunnel using scp or sftp ### 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. Get the port number of the tunnel ### Using scp or rsync To copy a file to the remote system over the tunnel via scp use ``` scp -P @: ``` 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 Use Filezilla for file transfers over a tunnel # Renaming and tagging of clients Change clients names and add more tags 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 be unpresize and you want to delete or change it. Default client name #### 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 = ""`. 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. {% hint style="danger" %} On Windows always use a text editor that supports UTF-8 and Unix Line Breaks. [Notepad++](https://notepad-plus-plus.org/downloads/) is ideal. The windows built-in notepad is not the best choice. {% endhint %} 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`. # Organize clients with groups Hostname refers to the local hostname of the operating system, not to the client's name. By default, local hostname and client name are equal, but if you [change it manually](broken://pages/xUOuk9F3OL0i4uUAxSJl) , consider the difference. # Activate the vault #### 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. Vault initializing # Manage users and permissions #### 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. 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. Assign a client to a user 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 are 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. Members of the Administrators group are granted full permission and can therefore perform any action on all clients. With the rport-plus plugin, you can control which user group is allowed to execute which command. With the rport-plus plugin, you can control which kind of tunnels a user group is allowed to create. # Troubleshoot common problems Learn how to resolve common issues quickly Here are the articles in this section: [Restart rport through a tunnel](https://2500109324-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fp4ON1axBW24W9NpMHB26%2Fuploads%2FCQgw8Hr0CBu4wWuXV9ii%2Frestart%20rport%20through%20a%20tunnel?alt=media)[Attributes file path not set](https://2500109324-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fp4ON1axBW24W9NpMHB26%2Fuploads%2F5lR5XlrI27hQma8luYr1%2Fattributes%20file%20path%20not%20set?alt=media)[Recover lost passwords](https://2500109324-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fp4ON1axBW24W9NpMHB26%2Fuploads%2FFPdB69FJBtP8HL97EHZU%2Frecover%20lost%20passwords?alt=media)[Client is not connecting](https://2500109324-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fp4ON1axBW24W9NpMHB26%2Fuploads%2F789EUylOsfvKCcZ1qreW%2Fclient%20is%20not%20connecting?alt=media)[Id is already in use](https://2500109324-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fp4ON1axBW24W9NpMHB26%2Fuploads%2FglB5BM1A22pDzGc12UPw%2Fid%20is%20already%20in%20use?alt=media)[PreviousManage users and permissions](broken://pages/ZK4bTtkwG2oDUbWWPZ0y)[NextRestart rport through a tunnel](https://2500109324-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fp4ON1axBW24W9NpMHB26%2Fuploads%2FCQgw8Hr0CBu4wWuXV9ii%2Frestart%20rport%20through%20a%20tunnel?alt=media) Last modified 2yr ago # Restart rport through a tunnel How to restart the rport client safely when connected via tunnel ### 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: ```bash 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.

Restart rport over rport on Linux

#### 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. ```powershell 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.

Restart rport over rport on Windows

# Attributes file path not set How to solve the “attributes file path not set” error ### 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. Error on changing labels and tags 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. {% hint style="danger" %} Be careful when **restarting rport if you are connected through an rport tunnel**. The restart would kill the tunnel and rport will not come up afterwards. 👉 Follow [these instruction](broken://pages/OAf07zG84jS3IqhyWpEY) to restart rport safely. {% endhint %} # Recover lost passwords Learn how to get access to the RPort server if you have lost all password 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 -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. Check where users and passwords are stored **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="" PASSWD_HASH=$(htpasswd -nbB password $NEW_PASSWD|cut -d: -f2) ``` Create a password hash **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** ``` DB_FILE=/var/lib/rport/user-auth.db cat < /dev/tcp// && 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 -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 of 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. {% code title="/etc/rinetd.conf" %} ``` # Open port 8345 and forward to 80. # bindadress bindport connectaddress connectport 0.0.0.0 8345 127.0.0.1 80 ``` {% endcode %} 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: {% code title="/etc/systemd/system/rinetd.service" %} ``` [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 ``` {% endcode %} 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 ``` # Id is already in use Solve connection errors caused by duplicated ids #### 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. id of the rport client #### 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. You can edit the `rport.conf` with an editor and insert a [randomly created UUID](https://www.uuidgenerator.net/). Restart the client and it will connect flawlessly. 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`. {% hint style="info" %} Starting with rport 0.6.0 the client can dynamically read the systemd id on start. That eliminates the need of copying `/etc/machine-id` to `rport.conf`. But it doesn't liberate you from the duty of creating unique machine ids on your network. {% endhint %} # Using the API RPort comes with a Restful API that enabled you to integrate RPort into your projects. 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. If you have command and/or scripts enabled on your clients, the API token can become very powerful. 🔥Taking full control over one or all clients might be possible with an API token. * Never communicate with the API without encryption (HTTPs). * Delete tokens that are not used anymore. The **base URL** of the API is `https:///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 ``` You can read the API documentation online, nicely rendered via Swagger, [here](https://apidoc.openrport.io/). Alternatively, will find the full API documentation (raw swagger file) on our [GitHub repository](https://github.com/openrport/openrport/blob/master/api-doc/openapi/openapi.yaml). # Create client credentials For mass-deployment ### 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 Linux

On Linux

On Windows

### Generate client credentials on Windows with PowerShell ```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 ```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}" ``` # RPort Technology Explained What happens behind the scenes ### **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. {% hint style="info" %} Don't get confused. The above describes how communication is encrypted via SSH. The tunnels are not limited to use SSH for remote access only. Any protocol can be used. See [below](about:/digging-deeper/rport-technology-explained#tunneling-for-remote-access-from-anywhere). {% endhint %} RPort uses the SSH library [GoSSH from Google](https://pkg.go.dev/golang.org/x/crypto/ssh). Only SSH2 is used with the [standard ciphers](https://cs.opensource.google/go/x/crypto/+/630584e8:ssh/common.go;l=38-42) `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. # Commands and Scripts Learn how to execute command and scripts from the browser without an interactive login. #### 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. {% code title="rport.conf" %} ``` [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\\.*'] ``` {% endcode %} See [all configuration options](https://github.com/openrport/openrport/blob/master/rport.example.conf#L132-L177) and more [configuration examples](https://oss.openrport.io/get-started/command-execution/). If you feel it were better not to give full control over the clients to the RPort server, you should script execution of. {% code title="rport.conf" %} ``` [remote-scripts] ## Enable or disable execution of remote scripts sent by server. ## Defaults: false #enabled = false ``` {% endcode %} {% hint style="info" %} If you have installed the client via the pairing script, scripts and commands are either enabled without restictions or fully disabled. To use command filtering you need to change the configuration file manually. {% endhint %} 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. Command execution on a single client Selecting `commands` or `scripts` on the top navigation gives you access to the parallel execution. parallel command execution # Executing commands Execute command on a single client ### 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. {% code title="rport.conf" %} ``` [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\\.*'] ``` {% endcode %} See [all configuration options](https://github.com/openrport/openrport/blob/master/rport.example.conf#L132-L177) and more [configuration examples](https://oss.openrport.io/get-started/command-execution/). {% hint style="danger" %} Allowing remote command without restrictions makes the RPort server very powerful. Persons who have access to the RPort server API or the webinterface can take full controll over connected clients. 👉 It's highly recommended to use two-factor authentication. {% endhint %} 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. Execution of two command in a single run. Bear in mind that the concatenation signs `&`, `;` , 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. {% code title="rport.conf" %} ``` allow = ['^systemctl (status|restart).*'] deny = [] order = ['allow','deny'] ``` {% endcode %} 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. Command concatenation rejected. 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"`. Executing powershell commands If you only want to allow restarting any service via PowerShell change your configuration as follows. ``` allow = ['^powershell \"(Get|Restart)-Service .*\"'] deny = ['(\||<|>|;|,|\n|&)'] order = ['allow','deny'] ``` {% hint style="info" %} While the PowerShell is case insentive, the regular expression for the filtering are not. They are case sensitive and the commands must by typed in with the correct capitalization. {% endhint %} # Executing scripts Learn how to execute scripts directly from the browser or via the API ### 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. ![Two options for script execution](https://1142160776-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MekeI9EovpQqbUTQSdM%2F-MgfcSmFdxikO59c2iij%2F-MgfvKmc3HBDcD04J6Aw%2Fimage.png?alt=media\&token=cb269f5d-c886-4c49-97f5-9c3c8cf62252) ### 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. {% embed url="" %} Execute PowerShell scripts with RPort {% endembed %} The video show how to install 7zip and notepad++ fully unattended with RPport using the following lines of PowerShell. {% code title="install-7zip.ps1" %} ``` 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" } ``` {% endcode %} {% code title="install-notepadd++.ps1" %} ``` 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" } ``` {% endcode %} ### 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`. ![Executing Python](https://1142160776-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MekeI9EovpQqbUTQSdM%2Fuploads%2FYpTdOwwDforyf0Pg9CvP%2Fimage.png?alt=media\&token=4b229c6d-44d2-4923-b04f-af26e29fd462) {% hint style="success" %} If no shebang is given, `/bin/sh` is used to execute your script. {% endhint %} ### 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.
Execute with any interpreter Register custom interpreters
# Tacoscript RPort provides its own scripting language to make complex tasks easy. ### 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](https://github.com/openrport/tacoscript). ### 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. {% tabs %} {% tab title="Windows (PowerShell)" %} ```powershell $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 ``` {% endtab %} {% tab title="Linux (Bash)" %} ```bash #!/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.openrport.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 ``` {% endtab %} {% endtabs %} # The scheduler Learn how to schedule scripts or command on a single client or on multiple clients concurrently 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. {% hint style="info" %} The scheduler runs only on the RPort server. Jobs are dispatched when due to the clients as regular script or command execution. All [security filters](https://github.com/cloudradar-monitoring/rport/blob/0.6.0/rport.example.conf#L139-L184) are applied.\ **If a client is disconnected, a job will not be caught up.** {% endhint %} ### 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. ![Create a script or command first](https://1142160776-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MekeI9EovpQqbUTQSdM%2Fuploads%2F5uA9hWxSk2q9DSnKUJaw%2Fschedule-create.png?alt=media\&token=1c691c5c-0e6c-4419-a0f8-80b895572925) ![Schedule a command or script](https://1142160776-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MekeI9EovpQqbUTQSdM%2Fuploads%2Fr7WpVAR13hBhryhLjUg6%2Fschedule-cron.png?alt=media\&token=59869294-8b73-47e3-a6e9-75a6be44c2a7) #### Supervise schedules From the "Schedules" tab, you get access to the reports. You can verify the success of all schedules jobs. ![List of schedules and their status](https://1142160776-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MekeI9EovpQqbUTQSdM%2Fuploads%2Fas9qPbMXseGx0QPTuLJl%2Fschedule-report.png?alt=media\&token=6d2fe84d-eb64-4b13-8997-9f5bf4a53a54) ![Detailed report](https://1142160776-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MekeI9EovpQqbUTQSdM%2Fuploads%2FnToy6zZPfmWSRU0zBDMH%2Fschedule-report-details.png?alt=media\&token=f7329482-010f-4ad5-bcfa-7108fbc3369d) ### 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`. ![Schedule a script for multiple clients](https://1142160776-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MekeI9EovpQqbUTQSdM%2Fuploads%2F8XWhmkW398boeARWlV1u%2Fmulti-schedule-create.png?alt=media\&token=9d9bcf15-012b-46e2-92f5-563a66d46ed2) #### 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. ![Supervise schedules on a global level.](https://1142160776-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MekeI9EovpQqbUTQSdM%2Fuploads%2FVNQtGJX93ZHmqxjl9PlM%2Fmulti-schedule-reports.png?alt=media\&token=8ef5baf2-5da5-403a-9313-f947bd61f40d) # File copy and reception Learn how to transfer files from your local desktop to remote clients 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. {% hint style="danger" %} File reception is enabled by default on the rport client. If you consider it insecure, turn it off in the `rport.conf` file. `[file-reception]`\ `enabled = false` {% endhint %} 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. ![Upload a file](https://1142160776-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MekeI9EovpQqbUTQSdM%2Fuploads%2Faz8iMDRL6nn5qP3BVluJ%2Fimage.png?alt=media\&token=25af2436-5727-4fac-8daa-34b8486bfb0c) # Client Configuration Options Fine tune the client configuration ​ [DIGGING DEEPER -PreviousFile copy and reception](broken://pages/FfrSD8cwaJWs8FodwfAX)[NextSupervision of OS updates](https://2500109324-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fp4ON1axBW24W9NpMHB26%2Fuploads%2FC6XHp3cqB8Ib6jvkpg3q%2Fsupervision%20of%20os%20updates?alt=media) # Supervision of OS updates Starting with rport client version 0.2.4 the supervision of available operating system updates is possible ### 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. {% hint style="info" %} Don't forget to restart the rport client after changing the configuration file. \ Use `systemctl restart rport`. {% endhint %} ⚠️ **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. {% tabs %} {% tab title="Debian & Ubuntu" %} {% code title="/etc/sudoers.d/rport-update-status" %} ``` rport ALL=NOPASSWD: SETENV: /usr/bin/apt-get update -o Debug\:\:NoLocking=true ``` {% endcode %} {% endtab %} {% tab title="SuSE" %} {% code title="/etc/sudoers.d/rport-update-status" %} ``` rport ALL=NOPASSWD: SETENV: /usr/bin/zypper refresh * ``` {% endcode %} {% endtab %} {% endtabs %} # Script and command execution ### 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'] ``` # Advanced client management Learn more about installing the client manually and all advanced configuration options Here are the articles in this section: {% content-ref url="/pages/1MFg2CYdbhcivPzubQXn" %} [Install the RPort client manually](/digging-deeper/advanced-client-management/install-the-rport-client-manually) {% endcontent-ref %} [Install the RPort client manually](https://2500109324-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fp4ON1axBW24W9NpMHB26%2Fuploads%2Fi7oK3XDl4n6cK4hZfzDK%2Finstall%20the%20rport%20client%20manually?alt=media)[Uninstall the RPort client](https://2500109324-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fp4ON1axBW24W9NpMHB26%2Fuploads%2F59oj8yeJgjFIWM9Y9W5M%2Funinstall%20the%20rport%20client?alt=media)[Run with SELinux](https://2500109324-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fp4ON1axBW24W9NpMHB26%2Fuploads%2FvVCVrXuWNVULFeEU9RxC%2Frun%20with%20selinux?alt=media)[PreviousScript and command execution](https://2500109324-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fp4ON1axBW24W9NpMHB26%2Fuploads%2FGCPF1o45twHWO4NqaSWp%2Fscript%20and%20command%20execution?alt=media)[NextInstall the RPort client manually](https://2500109324-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fp4ON1axBW24W9NpMHB26%2Fuploads%2Fi7oK3XDl4n6cK4hZfzDK%2Finstall%20the%20rport%20client%20manually?alt=media) # Install the RPort client manually Install the client on any device manually ### Preface While the preferred way to install the client is the pairing service, this option might not be feasible on devices with very limited resources. A shell like bash or many of the command line tools used for the automated creation of the configuration are very likely not available on devices likes routers, switches or NAS. To run the client, you need two files. 1. The **rport binary** that matches the CPU architecture or your device 2. The **rport.conf configuration** file with all credentials and details of your rport server ### Install the client binary The most versatile way to install the client binary is downloading the tar.gz package for the release page of our [GitHub repository](https://github.com/openrport/openrport/releases) 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. {% hint style="info" %} On Windows use notepad++ or some other editor that can handle Unix line breaks and Utf-8 encoding. The built-in windows' notepad is not suitable. {% endhint %} 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](https://www.uuidgenerator.net/version4). 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 `. Check what is the preferred way to start service on boot. Hook in rport there. # Uninstall the RPort client Learn how to remove the client ### 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`. ![RPort for Windows comes with an uninstaller.](https://1142160776-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MekeI9EovpQqbUTQSdM%2F-MksAfKoLyoA12Yezdl9%2F-MksDZJg0QcurXtN3FFn%2Fimage.png?alt=media\&token=c79b0157-2141-4f9c-940d-cf4a6223ec96) 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` {% hint style="info" %} **🧹 Keep your system tidy.** Very likely, the rport installer has also installed tacoscript. Go to `C:\Program Files\tacoscript` and execute `uninstall.bat` if you don't want to use tacoscript independently of rport. {% endhint %} # Run with SELinux # Server Maintenance {% content-ref url="/pages/CHZgLf3dzzXFxi5WxS6V" %} [Monitoring of RPortd](/digging-deeper/server-maintenance/monitoring-of-rportd) {% endcontent-ref %} {% content-ref url="/pages/xfXxADl61rxxlyGQkyfw" %} [Updating RPort](/digging-deeper/server-maintenance/updating-rport) {% endcontent-ref %} # Monitoring of RPortd Get notified about issues with your rport server 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 While there a many monitoring services available at different prices, we will explain how to do it with [Betteruptime.com](https://betterstack.com/better-uptime) as an example. For a reliable monitoring of a single RPort server, the free Basic plan is perfect. #### Create monitors On the left-side main menu click on `Monitors` and on the right side click the button "Create Monitor". When asked what to monitor, do not enter any URL, select "Alert us when the URL above, doesn't respond to a tcp port". The input form will change. Now enter as follows. * Host to monitor: \ * TCP Port: the port where clients connect * Keyword to find in response: leave empty * Send data to port: keep the default ![Create a monitor for the client connections](https://1142160776-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MekeI9EovpQqbUTQSdM%2Fuploads%2FSXnm1LQwaH0NpB6EDK2t%2Fbetteruptime-client-monitor.png?alt=media\&token=5d81a7dc-1fc8-405c-9049-79c2eea5c988) Next, create a monitor for the RPort API and the user interface. Enter the URL of your RPort API. If the port is not the default port 443, append the port to the URL separated by a colon. You should get a green checkmark. Unfold the “Advanced Setting” and enter a pronounceable monitor name like "RPort API/UI". \ On the SSL verification options enable "SSL expiration Alert 3 days before". ![Create a monitor for the API/UI](https://1142160776-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MekeI9EovpQqbUTQSdM%2Fuploads%2FQFkty4UrDft4vgPrMnnL%2Fbetteruptime-api-monitor.png?alt=media\&token=104730b3-7324-4b42-9acc-f0feac2f7b96) #### Monitor the disc space To monitor the disk space of your RPort sever with Better Uptime click on `Heartbeats` on the left-side main menu. On the right side, click “Create Heartbeat”. Create the heartbeat as follows: * What service will this heartbeat track?: “RPort Server Disc Space” * Expect a heartbeat every: 30 minutes * with a grace period of: 5 minutes ![Create a “disk heartbeat”](https://1142160776-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MekeI9EovpQqbUTQSdM%2Fuploads%2FluejvLNgfp9nziExa7XS%2Fbetteruptime-disk-heartbeat.png?alt=media\&token=a3b5fd0d-af17-4b99-b700-8cd22be8c023) After creating the heartbeat, a URL is created for you. Copy this URL to your clipboard and enter it to the below script on line 6. On the rport server, store the following script under `/usr/local/bin/discheartbeat.sh`. {% code title="/usr/local/bin/discheartbeat.sh" %} ```bash #!/bin/sh set -e # Set the threshold. If disc space used percent if above, your heartbeat fires an alert. MAX_ALLOWED=90 # Set the URL Better Uptime has created for your heartbeat URL="https://betteruptime.com/api/v1/heartbeat/???????" export LANG=en LANG=en df -h --output=target,fstype,pcent|grep -E -v "(tmpfs|Mounted)"| { while read -r LINE;do pused=$(echo $LINE|awk '{print $3}'|tr -d "%") fs=$(echo $LINE|awk '{print $1}') # Compare the used space percent with the threshold if [ "$pused" -gt "$MAX_USED_ALLOWED" ];then echo "Used space on $fs = $pused is above MAX_ALLOWED $MAX_ALLOWED"|logger -t discheartbeat exit 1 fi done curl -sf "${URL}" >/dev/null 2>&1 echo "all discs checked"|logger -t discheartbeat }sh ``` {% endcode %} Make the script executable and run it as a half-hourly cronjob. ``` chmod +x /usr/local/bin/discheartbeat.sh echo '*/30 * * * * root /usr/local/bin/discheartbeat.sh'>/etc/cron.d/discheartbeat ``` Now your discs are checked every 30 minutes. If none of your discs is filled by more than 90 percent, an "all good" confirmation will be sent to Better Uptime. If any disc exceeds the maximum allowed, the heartbeat is skipped, and you will receive an alert. To make sure your heartbeat is running, you can check the syslog by `grep discheartbeat /var/log/syslog`. On the list of active heartbeats, you will get a green light when your discs have enough space. ![Monitor the disc space of the RPort server.](https://1142160776-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MekeI9EovpQqbUTQSdM%2Fuploads%2FwP9Oh4gJLWoBVeZbMk76%2Fdisc-heartbeat-results.png?alt=media\&token=160bf9fa-8d9c-457b-9ad6-0aa21a3c68e8) # Updating RPort RPort is under active development. Keep your installation up-to-date. ### Update the RPort clients It's recommended to run your clients with the recent version of rport. We try to always keep server and client compatible, regardless of the version. Basic connectivity and the usage of tunnels should always be possible with clients running an older version than the server. An exception to that rule is the licence change from 0.9.12 to 1.0.0. **Clients >= 1.0 will not connect to an open-source server <= 0.9.13.** A fast and easy update of the rport clients can be done through the pairing service. If you have scripting with root privileges enabled, you can trigger a client update through the rport server. {% hint style="success" %} 💡It's safe to execute the update while **being connected** via SSH or RDP **through an RPort tunnel**. On Windows and Linux, the rport client is restarted delayed and from a decoupled background process. You will be disconnected, but the client reconnects, and you can create a new tunnel after the update. {% endhint %} #### On Linux ```bash set -e if [ $(id -u) -ne 0 ];then echo "Needs to run from the root account. Activate sudo!" false fi if which at; then true else echo "System is missing the at command." echo "Try 'dnf -y install at; pidof atd||systemctl start atd' on RHEL" echo "Try 'DEBIAN_FRONTEND=noninteractive apt-get -y --no-install-recommends install at' on Debian/Ubuntu" false fi curl -sf https://pairing.openrport.io/update > /tmp/rport-update.sh at now << EOF sleep 5 sh /tmp/rport-update.sh >/tmp/rport-update.log 2>&1 rm /tmp/rport-update.sh EOF echo "The rport client update will shortly start in the background." echo "If update fails, inspect /tmp/rport-update.log" ```

RPort client update on Linux

The Linux update script accepts parameters as follows: ``` sh rport-update.sh -h Usage rport-update.sh [OPTION(s)] Update the current version of RPort to the latest version. Options: -h print this help message -v [version] update to the specified version. -c update the rport client, default action -t use the latest unstable version (DANGEROUS!) -u uninstall the rport client and all configurations and logs -x enable script execution in rport.conf -d disable script execution in rport.conf -s create sudo rules to grant full root access to the rport user -n do not create sudo rules to grant full root access to the rport user ``` #### On Windows ```powershell cd $env:temp [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12 $url="https://pairing.openrport.io/update" Invoke-WebRequest -Uri $url -OutFile "rport-update.ps1" powershell -ExecutionPolicy Bypass -File .\rport-update.ps1 rm .\rport-update.ps1 -Force ``` ![Update the RPort client on Windows with RPort](https://1142160776-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MekeI9EovpQqbUTQSdM%2Fuploads%2F2pr82nYapRRvhk4j0zgH%2Frport-client-update-windows.png?alt=media\&token=a9029e22-ec7d-4ebf-969c-cac5f6c46da7) The Windows update script accepts parameters as follows: ```powershell PS C:\Users\Administrator> .\rport-update.ps1 -h Update the rport client. Invoking without parameters updates to the latest stable version. Parameters: -t Use the latest unstable version. -x Enable command and script execution without asking for confirmation. -d Disable command and script execution. -v [version] Upgrade to the specified version. ``` ### Update the RPort server We keep all major and minor versions of the `rportd` and the frontend compatible. **Do not run different major and minor versions of frontend and backend**. The rport server has database migrations built-in. But some tables are excluded from auto-migration. An update consists basically of replacing the old `rportd` binary by a newer version. If you need to change the database manually, we will provide SQL snippets. For a fast, secure and convenient update, use the update script as follows, read the security advice below first: {% code title="rportd-update.sh" %} ```bash curl -s https://get.openrport.io/update -o rportd-update.sh sudo -E bash rportd-update.sh ``` {% endcode %} 👉 After the update, use [SHIFT-Reload](https://en.wikipedia.org/wiki/Wikipedia:Bypass_your_cache) on your browser to **purge the old frontend from the cache**. If you already entered your licence details to the `rportd.conf` file, you must not export them to the environment before starting the update. # Backing up the rport server Perform regular backups ### Backup script Run the following script from cron to perform a backup of all relevant data needed to recover a rport server. ```bash #!/bin/sh # Backup the sqlite databases cd /var/lib/rport DBS=*.db for DB in $DBS;do echo $DB sqlite3 $DB ".backup '$DB.backup'" done # Pack and compress everything tar --exclude='*.db' \ -cvzf /var/backups/rportd-$(date +%Y-%m-%d-%H%M%S).tar.gz \ /var/lib/rport /etc/rport ``` {% hint style="info" %} The above script is made for Ubuntu/Debian Linux using the default backup folder `/var/backups`. On RedHat and derivates replace by a different folder where you like to store your backups or create `/var/backups` using `mdkir`. {% endhint %} {% hint style="warning" %} Make sure you copy the created backup file to some remote file server. {% endhint %} # Renewing certificates Set up auto-renewal of Let's encrypt certificates If your RPort server runs with Let's encrypt certificates, the certificates need to be renewed before they expire. On Debian and Ubuntu Linux `certbot` comes with an auto-renewal job. But this job needs some fine-tuning to work properly. {% hint style="danger" %} Starting with RPort 0.9.0 the below hooks are deployed by default by the server installer script. **If you installed before August 2022 review and change your hooks manually.** {% endhint %} ### Check the scheduler On Debian and Ubuntu, the `certbot` package should have installed a systemd time that checks all certificates for renewal twice a day. Check the file `/lib/systemd/system/certbot.timer` exists. The command `systemctl list-timers` should tell you, when `certbot.timer` run for the last time. ![Systemd times last run](https://1142160776-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MekeI9EovpQqbUTQSdM%2Fuploads%2F62XmjFarSkhDYlszel41%2Fcertbot-timer.png?alt=media\&token=1dd76531-9a0a-4819-b70a-f3d5d71932bd) ### Create hook files With the default settings, `certbot` cannot renew your certificates. The auto-renewal needs to be confirmed by a so-called [http-01 challenge](https://letsencrypt.org/de/docs/challenge-types/#http-01-challenge). Certbot must bring up a temporary web server on port 80. The policies of Let's encrypt don't allow using a different port. Usually RPort is using the port 80 and therefore `certbot` cannot renew. You must teach `certbot` how to stop RPort before the renewal and how to start RPort again. {% hint style="success" %} The below stop and start actions are only **executed if a renewal is due**. They are not executed everytime the certbot timer runs. By default cetbot renews 30 days before expiry. This means the hooks are executed every 60 days. {% endhint %} Execute the below script on your rport sever from the root account to create the hooks. ```bash cat << EOF > /etc/letsencrypt/renewal-hooks/pre/rport.sh #!/bin/sh echo "Stopping rportd for certificate renewal"|logger -t certbot systemctl stop rportd EOF chmod +x /etc/letsencrypt/renewal-hooks/pre/rport.sh cat << EOF > /etc/letsencrypt/renewal-hooks/post/rport.sh #!/bin/sh echo "Starting rportd after certificate renewal"|logger -t certbot systemctl start rportd EOF chmod +x /etc/letsencrypt/renewal-hooks/post/rport.sh bas ``` From now on, `certbot` will renew the certificates automatically. {% hint style="danger" %} You need the above hooks even if RPort is not running on port 80. Without the restart the renewed certificate is not loaded into the web server of rportd. {% endhint %} # FAQ Frequently asked questions We collected frequently asked questions. # How to use Cloudflare Q: I can use a Cloudflare proxy in front of my rport server? ### DNS Setup To use RPort with Cloudflare, you must set up two DNS records. 1. One, let's say `rport.example.com` for the API and the UI/dashboard 2. And one for accessing the tunnels, let's say `tunnels.rport.example.com` The first will point to the Cloudflare Proxy, and Cloudflare handles the certificate. Set up your firewall properly so access without Cloudflare is denied. Otherwise, you wouldn't benefit from the Cloudflare DOS protection. The second record, `tunnels.rport.exmaple.com` points directly to your rport server. ### RPort server configuration With the above DNS setup, you can generate a Let's encrypt certificate on the rport server. ``` certbot certonly -d tunnels.rport.exmaple.com \ -n --agree-tos --standalone \ --register-unsafely-without-email ``` You might need to stop rportd during the certificate request because certbot needs to bind to port 80 for the verification process. Use the created [certificate for the tunnels](https://github.com/openrport/openrport/blob/0.8.0/rportd.example.conf#L204-L205). Make sure tunnels [use the tunnel FQDN](https://github.com/openrport/openrport/blob/0.8.0/rportd.example.conf#L40). By default, tunnels, and the API/UI use the same FQDN. {% code title="/etc/rport/rportd.conf" %} ```toml [server] ... snip ...snap ## Optionally defines the hostname or IP address used to generate links pointing to running tunnels. ## By default, all links are relative to the URL of the API or UI. ## If you run the API/UI behind a reverse proxy that is incapable of forwarding raw TCP/UDP packets, ## you can specify a separated tunnel_host to access tunnels, bypassing the reverse proxy. tunnel_host = "tunnels.rport.example.com" ... snip ...snap tunnel_proxy_cert_file = "/etc/letsencrypt/live/tunnels.rport.exmaple.com/fullchain.pem" tunnel_proxy_key_file = "/etc/letsencrypt/live/tunnels.rport.exmaple.com/key.pem" ``` {% endcode %}