Setting up SSH connections
In this guide we will cover how to establish SSH connections for your Hathora processes. Enabling SSH connections should be used for testing and debugging purposes and should be disabled/removed for production deployments/applications.
There are 2 sections to this guide:
- Initial setup to enable SSH connections
- Connecting to a Hathora Process (once enabled)
Initial setup
1. Create SSH Key
To create a new SSH key, you can run:
ssh-keygen -t <SIGNING_METHOD>
# Example:
ssh-keygen -t ed25519
# ed25519 is preferred over rsa (faster and more efficient)
2. Configure your Hathora Application
- Navigate to your application and go to “Settings”
- Add additional port for 22, name it “ssh”
- Add an environment variable with “AUTHORIZED_KEYS” as Name and your entire
.pub
key contents as the Value- e.g.
ssh-ed25519 Ar12C3NzaC1lZDI1NTE5AAAAIGQFyacTe+nr2iJFWDOVL/Jw6yoUt5Ko6hPMEOLAeM2K
- To authorize more than 1 key, just separate keys with “;”
- e.g.
ssh-ed25519 <key1_value>;ssh-ed25519 <key2_value>
noteYou can name this environment variable (AUTHORIZED_KEYS) whatever you prefer, just make sure the name you use is reflected in the Shell script in the next step.
- e.g.
3. Add a new Shell script to start ssh
- This script should start the ssh listener before starting your game server
- This script needs to be included as part of your server build tarball (
.tgz
) that you ultimately upload to Hathora when deploying. - Example content:
#!/bin/bash
mkdir -p ~/.ssh
# Initialize the counter for the number of SSH keys added
count=0
# Loop through each SSH key, separated by ;
IFS=';' read -ra keys <<< "$AUTHORIZED_KEYS"
for key in "${keys[@]}"; do
echo "$key" >> ~/.ssh/authorized_keys
((count++))
done
echo "$count keys have been added to ~/.ssh/authorized_keys"
echo "Starting ssh.."
service ssh restart
echo "Starting game server..."
./YourGameServerExecutable # can also execute another init.sh script
~/.ssh/authorized_keys is a file that you can append multiple authorized SSH keys to (just need to separate with newline). Full docs here: https://ubuntu.com/server/docs/service-openssh
4. Update your Dockerfile to install sshd and run your new Shell script
# ... rest of Dockerfile
# Ensure that shell script to start SSH is copied (not needed if already copied by another step)
COPY run.sh run.sh
# Install openssh-server and configure
RUN apt-get update -y && \
apt install openssh-server -y && \
mkdir /var/run/sshd && \
echo 'PasswordAuthentication no' >> /etc/ssh/sshd_config
# IMPORTANT: this needs to replace your existing CMD or ENTRYPOINT at hte end of your Dockerfile
# You can move the previous command to the end of your `run.sh` file
ENTRYPOINT ["bash", "run.sh"]
Connecting to a Hathora Process
Once you've completed the inital steps, you're now ready to connect and start testing on a Hathora Process.
1. (One time) Set up SSH key pair
- If your team is using a shared SSH key for access, download the key and add it to:
- Windows:
C:\Users\<USERNAME>/.ssh/
- Mac/Linux:
~/.ssh/
- Windows:
- Note the path to the private key, as you will need it to connect
2. Find the Hathora process you want to connect to
- Find the application via https://console.hathora.dev/overview
- Find the process via “Recent Processes” table or via search
- If no existing processes, you can create one easily via the “Create Room” button near the top-right.
3. Find the host:port info for SSH connections
4. Connect via SSH
Open Command Prompt or Terminal and enter the following command:
# Template:
ssh -i "<path_to_key_from_step_1>" root@<host_from_hathora> -p <port_from_hathora>
# Example:
ssh -i "~/.ssh/id_ed25519" root@7lr6zn.edge.hathora.dev -p 51290
Additional guides
Unreal Server additional steps
Unreal server doesn’t allow it’s server to run as root
user, but sshd requires root
user to run.
- Add to
Dockerfile
(insert into the chained install command):apt -y install sudo && \
- Add to
run.sh
script (replace last line):sudo -u unreal bash -c ./your_game_server_binary
Using SCP to download files
Useful for downloading log files from Hathora process (with SSH enabled)
scp -i "$PATH_TO_PRIVATE_SSH_KEY" -P $HATHORA_PORT root@$HATHORA_HOST:$PATH_TO_FILE_TO_DOWNLOAD ./