sshconf: Lightweight SSH Config Library

Common errors

• Bad configuration option: <incorrect_option_name>

  cause A directive (keyword) in the SSH configuration file has a typo or is not recognized by the OpenSSH client.
  fix Correct the spelling of the SSH directive. Refer to `man ssh_config` for a list of valid options and their correct syntax. For example, `HostNamee` should be `Hostname`.

• Permission denied (publickey).

  cause The SSH client cannot use your private key for authentication because its file permissions are too open, or the SSH config file itself has incorrect permissions and is being ignored.
  fix Verify that your `~/.ssh` directory has permissions `700`, `~/.ssh/config` has `600`, and your private key file (e.g., `~/.ssh/id_rsa`) has `600`. Use `chmod 700 ~/.ssh` and `chmod 600 ~/.ssh/config ~/.ssh/id_rsa`.

• SSH client is not using the specific configuration options (e.g., wrong user, key, or port) I set for a host.

  cause Your `~/.ssh/config` file has conflicting `Host` patterns, and a more general pattern is matched first, preventing your specific host configuration from being applied.
  fix Reorder the `Host` entries in your `~/.ssh/config` file so that more specific host definitions (e.g., `Host myhost.example.com`) appear *before* more general ones (e.g., `Host *.example.com` or `Host *`). Use `ssh -vvv <hostname>` to debug which configurations are being applied.

Warnings

• gotcha The `save()` method overwrites the SSH configuration file from which the `SshConfig` object was initially loaded. Use `write(filepath)` to save changes to a different file, or carefully use `save()` if overwriting is intended.
  Fix: Always use `config.write('/path/to/new_config')` unless you explicitly want to overwrite the source file. Consider backing up your `~/.ssh/config` before using `save()`.
• gotcha When `sshconf` reads a configuration file containing `Include` directives and then writes or saves it, the included files' contents are merged into the main output file. This flattens the configuration and removes the original `Include` structure.
  Fix: Be aware that `Include` directives will be expanded. If you rely on separate include files for modularity, you may need to manage them manually or use `sshconf` only for specific sections.
• gotcha OpenSSH clients process configuration options based on the first matching `Host` entry. If you have overlapping patterns (e.g., `Host *.example.com` and `Host specific.example.com`), the order matters. Less specific patterns appearing before more specific ones can lead to unexpected configurations being applied.
  Fix: Arrange `Host` blocks in `~/.ssh/config` from most specific to least specific. For example, place `Host *` as the very last entry to ensure it only applies if no other host matches.
• gotcha SSH client configuration files (`~/.ssh/config`) and private key files (`~/.ssh/id_rsa`) require strict file permissions. Incorrect permissions (e.g., world-readable) will cause the SSH client to ignore them for security reasons, leading to authentication failures or ignored configurations.
  Fix: Ensure `~/.ssh` directory has `chmod 700`, `~/.ssh/config` and private key files have `chmod 600`. Use `chmod 700 ~/.ssh` and `chmod 600 ~/.ssh/config` (and for private keys).

Install

• pip install sshconf Install with pip

Imports

• read

  import sshconf
  config = sshconf.read('~/.ssh/config')

  Primary function to load an existing SSH configuration file.
• empty

  import sshconf
  config = sshconf.empty()

  Function to create an empty SshConfig object for a new configuration.

Quickstart

This quickstart demonstrates how to create a new SSH configuration, add and modify host entries, and then write the configuration to a file. It uses `sshconf.empty()` to start a new configuration and `write()` to save it, avoiding modification of your actual `~/.ssh/config` file for safety. Remember that `save()` will overwrite the file it was read from.

import sshconf
import os

# Create a temporary config file for demonstration
temp_config_path = os.path.expanduser('~/.ssh/config_temp')

# Ensure the .ssh directory exists
os.makedirs(os.path.dirname(temp_config_path), exist_ok=True)

# Start with an empty configuration
config = sshconf.empty()

# Add a new host entry
config.add(
    'devserver',
    Hostname='192.168.1.100',
    User='devuser',
    IdentityFile=os.path.expanduser('~/.ssh/id_rsa_dev')
)

# Update an existing entry or add a new parameter
config.set(
    'devserver',
    Port=2222,
    ForwardAgent='yes'
)

# Add another host with minimal options
config.add(
    'testserver',
    Hostname='test.example.com',
    User='testuser'
)

# Remove a parameter from a host
config.unset('devserver', 'ForwardAgent')

# Get configuration for a host
host_config = config.host('devserver')
print(f"Devserver config: {host_config.to_dict()}")

# Write the changes to a new file (or save() to overwrite original)
config.write(temp_config_path)

print(f"SSH config written to: {temp_config_path}")
print("Contents of the temporary config file:")
with open(temp_config_path, 'r') as f:
    print(f.read())

# Clean up the temporary file (optional)
# os.remove(temp_config_path)