rTerm Agent
The rTerm agent is responsilbe for accepting and authenticating remote terminal requets.
How it Works
The Basics
When the agent is running, it is connected to the rTerm Server, which is used to establish new connections. A new request can come from the rTerm CLI or rTerm Web CLI. The incoming request requires the current session id of the rTerm agent or needs to be a trusted device (see below). Assuming one of the two ids are presented to the signaling server, then the rTerm Agent receives the request. A P2P connection is then established and only them does rTerm Agent try to authenticate the client (this is done so no signatures are sent over the rTerm Server itself). rTerm Agent then starts the ssh authenication and if the private and public keys are available and valid, a new remote terminal session is started.
Networking/Availability
rTerm agent (and the corresponding CLIs) use WebRTC to find each other on the internet and establish a P2P connection. This allows rTerm to work inside of firewall/NATs or find devices as location or IPs change.
That said, rTerm was created to work between trusted devices. In order for a remote session to start the client needs to present long session ids and ssh private/public key authenication.
For extra security, the rTerm Server can be put behind a firewall. See rTerm Server for more details
Installation Instructions
Run the following command from the terminal and it will create a ~/rterm directory with all dependencies:
curl https://t.rterm.io/dist/rterm-agent/linux-x64/install.sh | bash
To run the agent simply run ~/rterm/rterm-agent, the agent will start a session that can be joined using the rTerm CLI or rTerm Web CLI.
Run the following command from the terminal and it will create a ~/rterm directory with all dependencies:
curl https://t.rterm.io/dist/rterm-agent/macos/install.sh | bash
Then run ~/rterm/rterm-agent from the terminal. See Usage secion for additonal steps.
Run the following command from the terminal and it will create a ~/rterm directory with all dependencies:
curl https://t.rterm.io/dist/rterm-agent/pi4/install.sh | bash
rTerm Agent can be added to the Dockerfile or added after the fact. Add this line(s) to your Dockerfile for example:
RUN apt update && apt upgrade -y
RUN apt install curl -y
RUN curl https://t.rterm.io/dist/rterm-agent/linux-x64/install.sh | bash
Are you interested in rTerm Agent for Windows? Let us know!
Usage
Running rTerm Agent
To run the agent, simple run ~/rterm/rterm-agent. The agent will provide instructions and a unique session id that can be used to connect from rTerm CLI or rTerm Web CLI.
Screenshot Starting rTerm Agent
Running rTerm Agent as a Service
Running rTerm locally is great for quick connections, but it soon becomes a hassle if you need to boot up the agent all the time. In order to resolve this, a service can be created to run.
When rTerm is installed a few additonal files are stored in the ~/rtern folder.
Run the ~/rterm/install-service.sh file to install the service. To uninstall the service a ~/rTerm/uninstall-service.sh has been provided as well.
Coming soon...
When rTerm is installed a few additonal files are stored in the ~/rtern folder.
Run the ~/rterm/install-service.sh file to install the service. To uninstall the service a ~/rTerm/uninstall-service.sh has been provided as well.
Coming soon...
Are you interested in rTerm Agent for Windows? Let us know!
Accessing Public Keys
Public keys are used to authenticate incoming connections. This authentication can be disable with the --authUsingSessionId flag, but public keys are used by default.
By default, rTerm Agent will look in the ~/.ssh/authorized_keys folder to validate signatures provided by the CLI.
To change this behavior, set one of the two environmnet variables:
RTERM_AUTHORIZED_KEYS_PATH: Provide the full path to a file. rTerm Agent expects this file to have 1 public key per line.
RTERM_PUBLIC_KEY_PATH: Provide the full path to a .pub file. rTerm Agent expect this file to contain exactly 1 public key.
Session Ids
Session Ids are the main way that rTerm connects the Agent with the CLIs. This Session Id tells the signaling server to establish to connection. The Session Id is generated by rTerm Agent (either manually or automatically) and then needs to be provided by the rTerm CLI or rTerm Web CLI to establish a connection.
When the rTerm Agent starts, a new Session Id is generated and presented inside the terminal. If rTerm Agent was started as a service, then you can find the Session Id under /tmp/.rterm-sessionId.
Starting a Remote Session without Keys
It is possible (but not recommended) to start a rTerm Agent session without requiring public/private keys. This is useful when connecting to the rTerm Agent the first time to store keys or if you need quick access to the server.
In order to disable ssh keys, use the flag --authUsingSessionId when starting rTerm Agent. Note, the Session Id is still required to start a remote session.
Advanced
Trusted Devices
As rTerm CLI and rTerm Web CLIs connect to the rTerm Agent, they become "trusted devices". This allows the CLIs to connect to the Agent without knowing the Session Id. The signaling server will present the current Session Id to trusted devices. The connection still verifies the public/private keys before starting a remote terminal session.
To become a trusted device, a CLI needs to connect to the rTerm Agent using a Session Id. After that, the signaling server, will store each device id as "trusted".
In addition, a .trustedDevices file can be stored inside the ~/rterm folder. This is useful when starting up servers/containers for the first time. This file expects one Device Id per line. Note: To make this even more useful, make sure the public key is also stored and then connections will be available on first boot.
To find the Device Id for a CLI, see the "Find My Device Id" section of either the rTerm CLI or rTerm Web CLI.
User/Permissions
The rTerm Agent can be run as root or any other user. The user running the Agent determines the permissions of the session.