> For the complete documentation index, see [llms.txt](https://docs.rumi.systems/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.rumi.systems/rumi-management/guides/controller/configuring-remote-hosts.md).

# Configuring Remote Hosts

This guide covers configuring SSH access for multi-host deployments with the Rumi Controller.

## Overview

The Controller uses SSH to execute commands on remote hosts and SCP to transfer files during provisioning. To deploy containers across multiple hosts, SSH access must be configured for each target host.

## SSH Configuration

### Authentication

The Controller supports SSH key-based authentication. The following properties configure SSH access:

| Property     | Description                                      |
| ------------ | ------------------------------------------------ |
| SSH user     | The username for SSH connections to target hosts |
| SSH key file | Path to the private key file for authentication  |
| SSH port     | The SSH port on the target host (default: 22)    |

These can be configured globally in `controller.conf` or per-container in the system's DDL model.

### Key-Based Authentication

1. Generate an SSH key pair (if not already available):

   ```bash
   ssh-keygen -t rsa -b 4096
   ```
2. Copy the public key to each target host:

   ```bash
   ssh-copy-id -i ~/.ssh/id_rsa.pub user@target-host
   ```
3. Configure the Controller with the private key path and SSH user.

### Passwordless Access

The Controller requires passwordless SSH access to target hosts. Ensure that:

* The SSH key is not passphrase-protected, or an SSH agent is running with the key loaded.
* The target host's `authorized_keys` file includes the Controller's public key.
* The target host allows key-based authentication.

## Host Configuration in DDL

Each container in the DDL model specifies its target host. The Controller uses this information to determine where to provision and launch each container.

For containers running on the local machine, set the host to `.` to bypass SSH entirely and execute operations directly.

## Firewall and Network Requirements

Ensure the following network connectivity:

| From            | To              | Port           | Purpose                    |
| --------------- | --------------- | -------------- | -------------------------- |
| Controller host | Target hosts    | 22 (SSH)       | Provisioning and launching |
| Target hosts    | Messaging bus   | Messaging port | Container communication    |
| Target hosts    | Controller host | Discovery port | Service discovery          |

## Troubleshooting

### Connection Timeout

If provisioning fails with a connection timeout:

* Verify SSH connectivity: `ssh -i <keyfile> <user>@<host>`
* Check that the SSH port is correct and not blocked by a firewall.
* Increase the connection handshake timeout via `nv.controller.containerconnecthandshaketimeout`.

### Permission Denied

If SSH authentication fails:

* Verify the SSH key file path is correct.
* Check file permissions on the private key (should be `600`).
* Ensure the public key is in the target host's `authorized_keys`.