Skip to main content

SSH Config Format

Import and export hosts using the standard OpenSSH configuration file format.

Overview​

SSH Config is the standard configuration format used by OpenSSH clients on Linux, macOS, and Windows. It's stored in ~/.ssh/config file and uses a simple text-based format.

Benefits:

  • ✅ Standard format across all platforms
  • ✅ Compatible with native SSH command
  • ✅ Human-readable and editable
  • ✅ Works with Git, VSCode, and other tools
  • ✅ No special export needed - just copy the file

SSH Config File Structure​

Format Example​

Host production-web
  HostName 192.168.1.100
  Port 22
  User admin
  IdentityFile ~/.ssh/prod_key

Host staging-server
  HostName staging.example.com
  Port 2222
  User ubuntu
  IdentityFile ~/.ssh/staging_key

Host dev-database
  HostName 192.168.1.101
  Port 3306
  User root

Supported Directives​

Xermius reads these directives:

DirectiveXermius FieldExample
HostHost NameHost production-web
HostNameHost AddressHostName 192.168.1.100
PortPortPort 22
UserUsernameUser admin
IdentityFileNote only*IdentityFile ~/.ssh/id_rsa

Note: IdentityFile paths are imported as comments. You'll need to import the actual key to Xermius keychain separately.

Importing SSH Config​

Step 1: Locate Your SSH Config​

Default locations:

Linux/macOS:

~/.ssh/config

Windows:

C:\Users\YourUsername\.ssh\config

Step 2: Open Import Dialog​

  1. Open Xermius
  2. Click NEW HOST dropdown
  3. Select Import Hosts
  4. Click SSH Config tab

Step 3: Select File or Paste Content​

Option A: Browse File

Click "Browse File"
→ Navigate to ~/.ssh/config
→ Click Open

Option B: Copy-Paste

1. Open ~/.ssh/config in text editor
2. Copy all content
3. Paste into import dialog

Step 4: Preview & Import​

┌──────────────────────────────────────────────┐
│ Import Preview                               │
├──────────────────────────────────────────────┤
│ Found 5 SSH config entries                   │
│                                              │
│ ✓ production-web                             │
│   admin@192.168.1.100:22                     │
│   # IdentityFile: ~/.ssh/prod_key           │
│                                              │
│ ✓ staging-server                             │
│   ubuntu@staging.example.com:2222            │
│   # IdentityFile: ~/.ssh/staging_key        │
│                                              │
│ ✓ dev-database                               │
│   root@192.168.1.101:3306                    │
│                                              │
│ ... 2 more                                   │
├──────────────────────────────────────────────┤
│        [Cancel]            [Import 5]        │
└──────────────────────────────────────────────┘
  1. Review hosts
  2. Click Import

Step 5: Configure SSH Keys​

If your config uses IdentityFile:

  1. Go to SSH Keys tab
  2. Click Import Key
  3. Select your SSH key file
  4. Go back to Hosts
  5. Edit each host
  6. Select the imported SSH key
  7. Save

Exporting to SSH Config​

Step 1: Select Hosts to Export​

  1. Select hosts in dashboard
  2. Or export all hosts

Step 2: Open Export Dialog​

  1. Click NEW HOST dropdown
  2. Select Export Hosts
  3. Click SSH Config tab

Step 3: Review Export Content​

Host production-web
  HostName 192.168.1.100
  Port 22
  User admin
  # SSH Key ID: key-abc-123

Host staging-server
  HostName staging.example.com
  Port 2222
  User ubuntu
  # SSH Key ID: key-def-456

Host dev-database
  HostName 192.168.1.101
  Port 3306
  User root

Note: SSH Key IDs are included as comments. You'll need to configure IdentityFile manually if using with native SSH.

Step 4: Copy or Download​

Option A: Copy to Clipboard

Click "Copy to Clipboard"
→ Paste into ~/.ssh/config

Option B: Download File

Click "Download File"
→ Save as config
→ Move to ~/.ssh/config

Using with Native SSH​

To use exported config with native SSH command:

Step 1: Edit Config File​

Open the downloaded config and add IdentityFile:

Host production-web
  HostName 192.168.1.100
  Port 22
  User admin
  IdentityFile ~/.ssh/prod_key  # Add this line

Step 2: Test Connection​

ssh production-web

Should connect without prompting for hostname/port/user!

Advanced Config Options​

Multiple Hosts with Same Settings​

Use wildcards and common settings:

Host prod-*
  User admin
  IdentityFile ~/.ssh/prod_key
  Port 22

Host prod-web-01
  HostName 192.168.1.100

Host prod-web-02
  HostName 192.168.1.101

Host prod-db-01
  HostName 192.168.1.102

Jump Host Configuration​

Host bastion
  HostName bastion.example.com
  User admin
  IdentityFile ~/.ssh/bastion_key

Host internal-server
  HostName 192.168.10.100
  User root
  ProxyJump bastion

Note: Xermius will import the host definitions but not ProxyJump directives. Configure jump hosts separately in Xermius.

Examples​

Example 1: Basic Web Servers​

Host web-01
  HostName 192.168.1.100
  Port 22
  User deploy
  IdentityFile ~/.ssh/web_key

Host web-02
  HostName 192.168.1.101
  Port 22
  User deploy
  IdentityFile ~/.ssh/web_key

Example 2: Different Ports​

Host api-server
  HostName api.example.com
  Port 2222
  User apiuser

Host database-server
  HostName db.example.com
  Port 3306
  User dbadmin

Example 3: Using Hostname Aliases​

Host prod
  HostName production.example.com
  Port 22
  User admin
  IdentityFile ~/.ssh/prod_key

Host stag
  HostName staging.example.com
  Port 22
  User admin
  IdentityFile ~/.ssh/staging_key

Now you can connect with short names:

ssh prod    # Instead of ssh admin@production.example.com
ssh stag    # Instead of ssh admin@staging.example.com

Troubleshooting​

No Hosts Found​

Problem: Import shows "No valid hosts found"

Solution:

  • Check file format - should have Host entries
  • Verify each Host has at least HostName directive
  • Check for syntax errors (missing spaces, typos)

Missing Values​

Problem: Port or username not imported

Solution:

  • SSH Config uses defaults if not specified
  • Default port: 22
  • Default user: Current system user
  • Add these manually after import if needed

IdentityFile Not Working​

Problem: SSH keys from config not working in Xermius

Solution:

  • SSH Config uses file paths for keys
  • Xermius uses keychain system
  • Import keys to Xermius keychain separately:
    1. SSH Keys tab → Import Key
    2. Select key file
    3. Assign to hosts

Special Characters in Host Names​

Problem: Host name with spaces or special chars

Solution:

  • SSH Config supports quotes for complex names: 
    Host "Production Web Server"
      HostName 192.168.1.100
  • Or use simple names without spaces

Tips & Best Practices​

Before Import​

✅ Backup your config - Copy ~/.ssh/config to safe location
✅ Review entries - Remove old/unused hosts
✅ Check keys exist - Verify IdentityFile paths are valid
✅ Note defaults - Document any special settings

During Import​

✅ Preview first - Always review before importing
✅ Check host count - Verify all hosts detected
✅ Note missing fields - Port/username may need adding

After Import​

✅ Test connections - Try connecting to a few hosts
✅ Import SSH keys - Add keys to keychain
✅ Organize - Create groups for better organization
✅ Add descriptions - Make notes for each host

When Exporting​

✅ Select carefully - Only export hosts you need
✅ Add IdentityFile - Manually add key paths
✅ Test config - Verify with ssh -F config hostname
✅ Set permissions - chmod 600 ~/.ssh/config

Integration with Other Tools​

Git over SSH​

After importing SSH config to Xermius, you can still use it with Git:

git clone git@github-work:company/repo.git

Where github-work is defined in your SSH config.

VSCode Remote SSH​

VSCode can read your SSH config for remote development:

  1. Install "Remote - SSH" extension
  2. VSCode reads ~/.ssh/config
  3. Connect to hosts defined in config

SCP and RSYNC​

Use SSH config aliases with file transfer tools:

scp file.txt production-web:/tmp/
rsync -avz /local/dir/ staging-server:/remote/dir/

Quick tip: Keep your SSH config in version control (without sensitive keys) for easy backup and sharing across machines!