Skip to content

SSH-SETUP.md

Latest commit

 

History

History
385 lines (272 loc) · 7.52 KB

SSH-SETUP.md

File metadata and controls

385 lines (272 loc) · 7.52 KB

SSH Configuration Guide

Complete guide to setting up SSH connections and tunnels

Prerequisites

You need one of the following:

  1. WSL (Windows Subsystem for Linux) - Recommended

    wsl --install

  2. Posh-SSH Module - Alternative if WSL unavailable

    Install-Module -Name Posh-SSH -Scope CurrentUser

Quick Setup

1. Create Configuration File

Copy the example config and edit it:

Copy-Item config.example.json config.json
notepad config.json

2. Configure Your Servers

Edit config.json with your server details:

{
  "ssh": {
    "credentialFile": "ssh-credentials.xml",
    "servers": {
      "prod": {
        "hostname": "production.example.com",
        "description": "Production server"
      },
      "staging": {
        "hostname": "staging.example.com",
        "description": "Staging server"
      },
      "aws": {
        "hostname": "ec2-xxx.amazonaws.com",
        "description": "AWS EC2 instance",
        "keyFile": "aws-key.pem"
      },
      "db": {
        "hostname": "database.example.com",
        "description": "Database server"
      }
    },
    "databasePorts": {
      "postgres": 5432,
      "mysql": 3306,
      "mssql": 1433,
      "mongodb": 27017,
      "redis": 6379,
      "oracle": 1521
    }
  }
}

3. Store SSH Credentials

Create encrypted credentials (Windows DPAPI - only works on your machine):

# Create creds directory
New-Item -Path ".\creds" -ItemType Directory -Force

# Store your credentials
$cred = Get-Credential -UserName 'your-ssh-username'
$cred | Export-Clixml '.\creds\ssh-credentials.xml'

Security Note: The credential file is encrypted using Windows DPAPI and can only be decrypted by your Windows user account on this machine.

4. Test Your Connection

cssh prod                         # Connect to 'prod' server

Configuration Reference

Server Configuration

Each server entry in config.json:

"servers": {
  "alias": {
    "hostname": "server.example.com",
    "description": "Optional description",
    "keyFile": "optional-key.pem"
  }
}
Field Required Description
alias Yes Short name for the server (used in commands)
hostname Yes Full hostname or IP address
description No Human-readable description
keyFile No SSH key file name (.pem) in creds directory

Database Port Shortcuts

Customize database port shortcuts:

"databasePorts": {
  "postgres": 5432,
  "postgresql": 5432,
  "mysql": 3306,
  "mariadb": 3306,
  "mssql": 1433,
  "sqlserver": 1433,
  "mongodb": 27017,
  "mongo": 27017,
  "redis": 6379,
  "oracle": 1521,
  "custom-db": 9999
}

Credential File

Specify a custom credential file name:

"ssh": {
  "credentialFile": "my-credentials.xml",
  ...
}

The file is always stored in the creds subdirectory.

Usage Examples

Basic SSH Connection

# Using server alias
cssh prod

# Using direct hostname
cssh server.example.com

SSH Tunnels

Database Tunnels:

# PostgreSQL (default port 5432)
tunnel prod postgres

# MySQL (default port 3306)
tunnel prod mysql

# MongoDB (default port 27017)
tunnel prod mongodb

Custom Ports:

# Remote port 5432, local port 5433
tunnel prod postgres 5433

# Explicit port numbers
tunnel prod 5432 5433

Tunnel to Internal Host:

# Connect to internal database via jump host
tunnel prod 5432 5432 -RemoteHost db.internal.example.com

Tunnel Workflow:

+-------------+        +-------------+        +-------------+
|  Your PC    |  SSH   |   Server    |  TCP   |  Database   |
| localhost:  |------->|   (prod)    |------->|  Internal   |
|    5432     |        |             |        |    :5432    |
+-------------+        +-------------+        +-------------+

Multiple Credential Files

For different servers with different credentials:

1. Create Multiple Credential Files

# Production credentials
$prodCred = Get-Credential -UserName 'prod-user'
$prodCred | Export-Clixml '.\creds\prod-credentials.xml'

# Development credentials
$devCred = Get-Credential -UserName 'dev-user'
$devCred | Export-Clixml '.\creds\dev-credentials.xml'

2. Switch Between Credentials

Update config.json when switching:

"ssh": {
  "credentialFile": "prod-credentials.xml",
  ...
}

WSL Setup (Recommended)

WSL provides better SSH compatibility and terminal handling.

Install WSL

wsl --install

First Connection Setup

On first SSH connection, the toolkit will automatically install sshpass in WSL:

Installing sshpass in WSL (one-time setup)...

This enables password-based SSH authentication.

Manual WSL Setup

If needed, manually install sshpass:

wsl bash -c "sudo apt-get update && sudo apt-get install -y sshpass"

SSH Key Files (.pem)

For key-based authentication (common with AWS, cloud providers):

1. Place Key File in Creds Directory

# Copy your .pem file to the creds directory
Copy-Item 'C:\Downloads\my-server-key.pem' '.\creds\my-server-key.pem'

2. Configure Server with Key File

Add keyFile to your server config:

"servers": {
  "aws-prod": {
    "hostname": "ec2-xxx.compute.amazonaws.com",
    "description": "AWS Production",
    "keyFile": "my-server-key.pem"
  }
}

3. Create Credential File for Username

Key file auth still needs a username (stored in credential file):

$cred = Get-Credential -UserName 'ec2-user'
$cred | Export-Clixml '.\creds\ssh-credentials.xml'

Tip: Password field can be anything when using key files - only username is used.

4. Connect Using Key File

cssh aws-prod                    # Uses key file automatically
tunnel aws-prod postgres         # Tunnels also support key files

SSH Keys (Generate New)

To generate and install new SSH keys:

1. Generate SSH Key

wsl bash -c "ssh-keygen -t ed25519 -C 'your_email@example.com'"

2. Copy Key to Server

wsl bash -c "ssh-copy-id username@server.example.com"

3. Export Private Key for Toolkit

# Copy private key to creds directory
wsl bash -c "cat ~/.ssh/id_ed25519" | Set-Content '.\creds\my-key.pem'

Then configure keyFile in your server config as shown above.

Security Best Practices

  1. Never commit config.json or credential files

    • Add to .gitignore: 
      config.json
creds/

  2. Use strong, unique passwords for SSH

  3. Use SSH key files for production servers (more secure than passwords)

  4. Protect key files - ensure .pem files have restricted permissions

  5. Limit server access - only configure servers you need

  6. Rotate credentials periodically

Connection Methods

The toolkit uses different methods based on availability:

Priority Method Requirements
1 WSL + key file WSL installed, keyFile configured
2 WSL + sshpass WSL installed, password auth
3 Posh-SSH + key file Posh-SSH module, keyFile configured
4 Posh-SSH + password Posh-SSH module installed

Check Available Methods

# Check WSL
wsl --version

# Check Posh-SSH
Get-Module -ListAvailable Posh-SSH

See Also