# Adding an ssh connection to a server
How to let `mmo.admin` reach a new server over ssh, with a key held by ssh-agent — the preferred path of
[Credentials](deploy.md#credentials). Nothing secret ends up in a file the project commits.
The examples use a server reached as `user@server.example.com` on port `60606`, declared under the alias
`myserver`. Replace all three.
## 1. A key
Skip this if `~/.ssh/id_ed25519` already exists.
```bash
ssh-keygen -t ed25519 -C "you@example.com"
```
Give it a passphrase: ssh-agent holds the unlocked key, so you type it once per session, not once per deploy.
```bash
eval "$(ssh-agent -s)" # only if no agent is running
ssh-add ~/.ssh/id_ed25519
```
## 2. The public key on the server
`ssh-copy-id` asks for the server's password one last time and appends the key to `~/.ssh/authorized_keys`
there. The port goes in `-p` — it does not accept `host:port`.
```bash
ssh-copy-id -i ~/.ssh/id_ed25519.pub -p 60606 user@server.example.com
```
Without `ssh-copy-id`, or on a webspace whose panel takes the key instead (IONOS, OVH mutualisé, ...), paste
the contents of `~/.ssh/id_ed25519.pub` there.
## 3. The alias, in the project
The alias goes in `deploy.ssh.config`, at the project's root beside `deploy.json` — git-ignored, mode `0600`.
**Not** in `~/.ssh/config`: deploying never reads that one (`setup` only offers its values to copy).
```
Host myserver
HostName server.example.com
User user
Port 60606
IdentityFile ~/.ssh/id_ed25519
```
```bash
chmod 600 deploy.ssh.config
```
Only `Host`, `HostName`, `Port`, `User` and `IdentityFile` are read ([`SshConfig`](php/helpers/SshConfig.md#sshconfig)).
A server that needs `ProxyJump`, `Match` or `Include` has to be wired by hand through
[`Server::$shell`](php/entities/Server.md#server-shell).
It is an ordinary ssh config, so this reaches the server exactly as a deployment does:
```bash
ssh -F deploy.ssh.config myserver
```
## 4. The server, in deploy.json
```json
{"servers": {"myserver": {"sshAlias": "myserver", "auth": "agent", "fingerprint": "a1:b2:c3:..."}}}
```
`sshAlias` and `fingerprint` are public — commit them. The fingerprint is the server's host key, MD5 or SHA1
in hex: without it, the connection trusts whatever answers at that address. Don't copy it from
`ssh-keygen -l`, whose default `SHA256:` form the ssh2 extension cannot compare.
## Or let setup do steps 3 and 4
```bash
php scripts/admin.php setup --step=servers
```
It asks how the server is reached, writes the `Host` entry of `deploy.ssh.config` (offering the values of
`~/.ssh/config` when that has the alias), reads and pins the host key, and prints its MD5 to check against
`ssh-keygen -l -E md5 -f /etc/ssh/ssh_host_*_key.pub`, run on the server. Steps 1 and 2 stay yours.
## Check
```bash
php scripts/admin.php doctor
```
reports, for each server, which path it resolved through, whether its host key is pinned, and whether `tar`, a
sha256 tool and `curl` are there.