Using OpenSSH Configuration Files

Net::SSH can read and apply settings from standard OpenSSH configuration files (e.g., ~/.ssh/config and /etc/ssh/ssh_config). This allows you to centralize your SSH settings and use them seamlessly in your Ruby scripts.

How it Works

By default, Net::SSH.start automatically loads configuration from the following files if they exist:

~/.ssh/config (user-specific configuration)
/etc/ssh_config (system-wide configuration)
/etc/ssh/ssh_config (another common location for system-wide configuration)

Settings are applied based on the Host pattern that matches the hostname you provide to Net::SSH.start.

Example

Consider the following ~/.ssh/config file:

Host my-server
  HostName 192.168.1.100
  User myuser
  Port 2222
  ForwardAgent yes
  IdentityFile ~/.ssh/my-server-key

Host *.internal.company.com
  User admin
  ProxyCommand ssh gateway.company.com -W %h:%p

You can connect to my-server using its alias:

require 'net/ssh'

# Net::SSH will automatically use the settings for 'my-server':
# - HostName: 192.168.1.100
# - User: myuser
# - Port: 2222
# - ForwardAgent: true
# - IdentityFile: ~/.ssh/my-server-key
Net::SSH.start('my-server') do |ssh|
  puts ssh.exec!('hostname')
end

Controlling Configuration Loading

You can control this behavior with the :config option in Net::SSH.start:

true (default): Load default OpenSSH configuration files.
false: Do not load any configuration files.
String or Array of Strings: Load only the specified configuration file(s).

# Disable loading any config files
Net::SSH.start('host', 'user', config: false)

# Load only a specific project configuration file
Net::SSH.start('host', 'user', config: 'conf/ssh_config')

Supported Directives

Net::SSH supports a subset of the most common OpenSSH directives. Here is the list of supported keywords and how they map to Net::SSH options:

OpenSSH Directive	Net::SSH Option	Notes
`BindAddress`	`:bind_address`	The local IP address to bind to when connecting.
`ChallengeResponseAuthentication`	`:auth_methods`	Enables `keyboard-interactive`.
`KbdInteractiveAuthentication`	`:auth_methods`	Enables `keyboard-interactive`.
`CertificateFile`	`:keycerts`	Path to a certificate file.
`CheckHostIP`	`:check_host_ip`	Whether to check the host IP in `known_hosts`.
`Ciphers`	`:encryption`	A comma-separated list of preferred ciphers.
`Compression`	`:compression`	Enables compression (`yes`/`no`).
`CompressionLevel`	`:compression_level`	Compression level (1-9).
`ConnectTimeout`	`:timeout`	Connection timeout in seconds.
`FingerprintHash`	`:fingerprint_hash`	Algorithm for fingerprints (`MD5` or `SHA256`).
`ForwardAgent`	`:forward_agent`	Enables SSH agent forwarding (`yes`/`no`).
`GlobalKnownHostsFile`	`:global_known_hosts_file`	Path to the global known hosts file.
`HostBasedAuthentication`	`:auth_methods`	Enables `hostbased` authentication.
`HostKeyAlgorithms`	`:host_key`	A comma-separated list of preferred host key algorithms.
`HostKeyAlias`	`:host_key_alias`	Alias to use when looking up the host key.
`HostName`	`:host_name`	The real hostname to connect to. Supports `%h` substitution.
`IdentityAgent`	`:identity_agent`	Path to the SSH agent socket.
`IdentityFile`	`:keys`	Path to a private key file.
`IdentitiesOnly`	`:keys_only`	Use only keys from `IdentityFile` (`yes`/`no`).
`Macs`	`:hmac`	A comma-separated list of preferred HMAC algorithms.
`NumberOfPasswordPrompts`	`:number_of_password_prompts`	How many times to prompt for a password.
`PasswordAuthentication`	`:auth_methods`	Enables `password` authentication.
`Port`	`:port`	The port to connect to.
`PreferredAuthentications`	`:auth_methods`	A comma-separated list of preferred authentication methods.
`ProxyCommand`	`:proxy`	A command to execute to connect to the server.
`ProxyJump`	`:proxy`	A jump host to proxy through.
`PubKeyAuthentication`	`:auth_methods`	Enables `publickey` authentication.
`RekeyLimit`	`:rekey_limit`	Maximum data to transfer before rekeying (e.g., `1G`, `256M`).
`SendEnv`	`:send_env`	A space-separated list of environment variables to send.
`SetEnv`	`:set_env`	A space-separated list of `KEY=value` pairs to set.
`StrictHostKeyChecking`	`:verify_host_key`	Controls host key verification (`yes`, `no`, `accept-new`).
`User`	`:user`	The username to log in with.
`UserKnownHostsFile`	`:user_known_hosts_file`	Path to the user's known hosts file.
`Include`		Includes configuration from other files.