SSH Config in Practice: Use One Server Name in Terminals and Scripts

A server shortcut works in your terminal, but a script reports Could not resolve hostname. Before changing DNS settings, check how the shortcut was defined.

This tutorial is for readers who can already connect to a Linux server using its address, username, and port. We will turn that working command into a reusable SSH configuration, check it locally, and use it to download a remote file.

Method 1: Identify what the shortcut actually runs

Suppose your .zshrc contains this example:

alias blogbox='ssh -p 22222 deploy@192.0.2.10'

Run these commands in the terminal where the shortcut works:

type blogbox
alias blogbox

Compare these two commands:

blogbox
ssh blogbox

With an ordinary alias like the one above, the first command expands into the saved SSH command. In the second command, blogbox is an argument to SSH. A shell alias alone does not create an SSH host entry or a DNS record.

There is also a startup-file difference: zsh reads .zshrc for interactive shells. A non-interactive invocation should not be expected to load aliases from that file. See the zsh startup-file documentation.

You can inspect the definitions without loading the whole file:

grep -n 'blogbox' ~/.zshrc

Do not make a deployment script depend on sourcing your interactive shell settings. Put the connection details in the SSH client’s configuration.

Setup: Check the client

Run this on your local computer:

ssh -V
man ssh
man ssh_config

On Debian or Ubuntu, install the client if it is missing:

sudo apt update
sudo apt install openssh-client

The following example uses 192.0.2.10, deploy, and port 22222 as sample connection details. Replace them with the address, remote account, and SSH port from a command that already works for you. The example IP is not a live demonstration server.

Method 2: Create a reusable host entry

Prepare the local configuration file without truncating existing content:

mkdir -p ~/.ssh
chmod 700 ~/.ssh
touch ~/.ssh/config
chmod 600 ~/.ssh/config
cp -p ~/.ssh/config ~/.ssh/config.backup.$(date +%Y%m%d%H%M%S)

Open ~/.ssh/config in your editor. Add the following block near the beginning, before broad entries such as Host *. If Host blogbox already exists, edit that block instead of creating a duplicate.

Host blogbox
    HostName 192.0.2.10
    User deploy
    Port 22222

Host is the name you type; the other three settings select the destination, account, and port. Most SSH configuration options use the first value found, which is why specific entries belong before broad defaults. See the OpenSSH configuration manual.

If your working command uses a specific private key, add its actual local path inside the same block:

    IdentityFile ~/.ssh/id_ed25519_blog
    IdentitiesOnly yes

These two lines are optional. Add them only when that key exists and its public key is authorized for the remote account. IdentitiesOnly limits the identities offered for authentication; it does not install a key on the server. See IdentityFile and IdentitiesOnly.

Validation: Inspect settings before connecting

Print the evaluated configuration:

ssh -G blogbox | awk '$1 ~ /^(hostname|user|port)$/ { print }'

With the sample block, expect these values, possibly in a different order:

user deploy
hostname 192.0.2.10
port 22222

ssh -G evaluates configuration and exits without opening an SSH session. It checks your settings, not whether the destination is reachable or authentication will succeed. See the SSH command manual.

After replacing the sample details, test the real connection:

ssh blogbox 'hostname; whoami; pwd'

The result should identify your server, remote account, and initial working directory. On a first connection, verify the host fingerprint through your server provider or another trusted channel before accepting it.

Now try the same command from a non-interactive shell:

sh -c 'ssh blogbox "hostname"'

This workflow no longer needs the blogbox shell alias. It still needs the SSH configuration and authentication material available to the local user running the command.

Use the same name for file transfers and scripts

For a Hugo site stored at /home/wwwroot/example.com, inspect the project without changing it:

ssh blogbox 'cd /home/wwwroot/example.com && pwd && ls content'

Adjust the project path to your server. To download its configuration into a new temporary directory:

download_dir=$(mktemp -d)
scp blogbox:/home/wwwroot/example.com/hugo.toml "$download_dir/hugo.toml"
ls -l "$download_dir/hugo.toml"

SCP uses the SSH host configuration too. Without the host entry, the equivalent transfer uses uppercase -P for the port:

scp -P 22222 deploy@192.0.2.10:/home/wwwroot/example.com/hugo.toml "$download_dir/hugo.toml"

Do not substitute lowercase -p: SCP uses it to preserve file timestamps and mode bits. See the SCP manual.

For an unattended read-only check, first verify interactive login and arrange key-based authentication, including an unlocked agent if your key needs one. Then run:

ssh -o BatchMode=yes -o ConnectTimeout=10 blogbox \
  'cd /home/wwwroot/example.com && test -r hugo.toml && printf "project readable\n"'

BatchMode disables authentication prompts, so missing credentials cause failure instead of a password question. ConnectTimeout bounds connection setup; it is not a time limit for the remote command. See the OpenSSH option reference.

Troubleshooting

1. Still getting “Could not resolve hostname”

Repeat the ssh -G check. If it prints hostname blogbox, inspect the spelling of the Host entry and the local account running SSH. To explicitly select your file:

ssh -F ~/.ssh/config -G blogbox

A CI runner or another operating-system user has its own home directory and configuration. Provision the entry and credentials there as part of that environment’s setup.

2. SSH uses an unexpected account or port

Inspect the configuration file with line numbers:

nl -ba ~/.ssh/config

Look for duplicate Host blogbox entries and earlier matching defaults, including included files. Move the specific entry before conflicting defaults, then repeat ssh -G blogbox. Also check whether the calling command supplies its own username or port.

3. “Permission denied (publickey)”

Inspect an actual connection attempt:

ssh -v blogbox 'true'

Check the selected user and offered key. If you configured the optional identity above, verify the file and its permissions:

ls -l ~/.ssh/id_ed25519_blog
chmod 600 ~/.ssh/id_ed25519_blog

If the key exists but is rejected, confirm that its public key is authorized for the configured account on the server. A correct host entry cannot grant access by itself.

4. Connection refused or timed out

If the evaluated address and port are correct, check the server’s SSH listener, firewall, and network path. Retry with diagnostics:

ssh -v -o ConnectTimeout=10 blogbox 'true'

Changing a shell alias will not repair a service that is unreachable at the configured address and port.

Summary

Start with a working SSH command, move its destination settings into one Host entry, and verify the result with ssh -G. Then reuse that name for login, SCP, and scripts, checking authentication separately before unattended runs.

To organize the project commands you run after connecting, continue with the just command-runner tutorial.