OpenRPort

OpenRPort is a remote server management system that establishes secure SSH tunnels to devices inside protected intranets. It consists of a server (rportd) and client (rport) that communicate via SSH to provide remote access, command execution, file transfer, and system monitoring.

---

Table of Contents

• Client Installer
  • Server Configuration
  • Install
  • Update
  • Uninstall
  • Version Check
• Configuration
  • Command Policy

---

Client Installer

The server provides HTTP endpoints to generate installer, update, and uninstall scripts for Linux and Windows clients. The OS is auto-detected via User-Agent or can be set explicitly with the os query parameter.

Server Configuration

Add the following to your rportd.conf under [server]:

## Custom repository URL for client binary downloads.
## Default: "https://github.com/netzint/openrport"
repository_url = "https://github.com/netzint/openrport"

## Custom name for the installed client binary and service.
## This allows whitelabeling the client on target systems.
## Default: "openrport"
installer_name = "openrport"

## Auto-register each installed client on the server.
## When enabled, a client auth entry with a random password is created
## and injected into the install script automatically.
## When disabled, each client must be registered manually after installation.
## Default: true
installer_autoregister = true

Install

Generates a full install script that downloads the client binary, creates a config file, sets up a system service, and starts the client.

Endpoint: GET /client/install

Parameter	Required	Description
name	Yes	Client name. Used as auth ID and service identifier. If the name starts with a 5-digit number followed by a dash (e.g. 12345-server), the number is automatically added as a tag.
os	No	linux or windows. Auto-detected from User-Agent if omitted.
replace	No	Set to true to replace an existing client auth entry. Without this, an existing auth with the same name returns HTTP 409.
proxy	No	HTTP proxy URL (e.g. http://proxy:8080). Used for the binary download and written to the client config.

Linux:

curl -fsSL "https://your-server/client/install?name=myserver" | bash

Linux with proxy:

curl -fsSL -x "http://proxy:8080" "https://your-server/client/install?name=myserver&proxy=http://proxy:8080" | bash

Note: -x is needed so that curl itself can reach the server through the proxy. The proxy query parameter ensures the generated install script also uses the proxy for downloading the client binary, and writes it into the client config for ongoing use.

Windows (PowerShell):

iwr "https://your-server/client/install?name=myserver&os=windows" | iex

Windows with proxy:

iwr -Proxy "http://proxy:8080" "https://your-server/client/install?name=myserver&os=windows&proxy=http://proxy:8080" | iex

Note: -Proxy is needed so that Invoke-WebRequest itself can reach the server through the proxy. The proxy query parameter ensures the generated install script also uses the proxy for downloading the client binary, and writes it into the client config for ongoing use.

Replace existing client auth:

curl -fsSL "https://your-server/client/install?name=myserver&replace=true" | bash

What the install script does

Linux:

1. Creates a service user and directories (/etc/<name>, /var/log/<name>, /var/lib/<name>)
2. Downloads and extracts the latest release from the configured repository
3. Installs the binary to /usr/local/bin/<name>
4. Generates a TOML config file at /etc/<name>/<name>.conf
5. Creates a sudoers entry for the service user
6. Creates and starts a systemd service

Windows:

1. Creates directories under C:\Program Files\<name>
2. Downloads and extracts the latest release
3. Installs the binary as <name>.exe
4. Generates a TOML config file in the install directory
5. Creates and starts a Windows service

Update

Generates a script that downloads the latest binary and replaces the running one.

Endpoint: GET /client/update

Parameter	Required	Description
os	No	linux or windows. Auto-detected from User-Agent if omitted.

Linux:

curl -fsSL "https://your-server/client/update" | bash

Windows (PowerShell):

iwr "https://your-server/client/update?os=windows" | iex

What the update script does

1. Detects architecture
2. Downloads the latest release
3. Stops the running service
4. Replaces the binary
5. Starts the service

Uninstall

Generates a script that completely removes the client from the system.

Endpoint: GET /client/uninstall

Parameter	Required	Description
os	No	linux or windows. Auto-detected from User-Agent if omitted.

Linux:

curl -fsSL "https://your-server/client/uninstall" | bash

Windows (PowerShell):

iwr "https://your-server/client/uninstall?os=windows" | iex

What the uninstall script does

Linux: Stops and disables the service, removes binary, config, logs, data directory, sudoers entry, and service user.

Windows: Stops and removes the service, deletes the install directory.

Version Check

Returns the server version and repository URL.

Endpoint: GET /client/version

curl -s "https://your-server/client/version"

---

Configuration

Command Policy

You can restrict which commands are allowed to run on clients via the server config:

## Path to a TOML file defining allowed commands per OS.
## The list is sent to clients during connection setup.
## Default: not set
command_policy_file = "/etc/rport/command-policy.toml"

Example /etc/rport/command-policy.toml:

[linux]
allow = [
  '/usr/bin/apt-get update',
  '/usr/bin/apt-get upgrade -y',
]

[windows]
allow = [
  'C:\\Windows\\System32\\ipconfig.exe /all',
]

[global]
allow = [
  'hostname',
]