Skip to main content

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​

  1. Navigate to your application and go to “Settings”
  2. Add additional port for 22, name it “ssh” Port Config
  3. 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> Host
      note

      You 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.

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
note

~/.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/
  • 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 Recent processes
    • 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​

Host

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.

  1. Add to Dockerfile (insert into the chained install command): apt -y install sudo && \
  2. 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 ./

SCP