dotfiles/docs/SSH_TMUX_INTEGRATION.md

SSH + Tmux Integration Guide

Advanced workflows for managing SSH connections and tmux workspaces on Arch/CachyOS.

Table of Contents

• SSH Manager Overview
• Basic SSH Management
• Tmux Workspace Basics
• SSH + Tmux Integration
• Workflow Examples
• Advanced Features
• Multi-Server Management
• Troubleshooting

---

SSH Manager Overview

The SSH manager stores connection profiles and integrates seamlessly with tmux for session management.

Features:

• Save and organize SSH connections
• Auto-create tmux sessions per connection
• Quick fuzzy search and connect
• Deploy dotfiles to remote machines
• Support for custom SSH options
• No external dependencies (pure bash)

---

Basic SSH Management

Saving Connections

ssh-save <profile> <connection> [port] [key] [description]

Examples:

# Basic SSH
ssh-save prod user@prod.example.com

# With custom port
ssh-save prod user@prod.example.com 2222

# With SSH key
ssh-save prod user@prod.example.com 22 ~/.ssh/prod_key

# With description
ssh-save prod user@prod.example.com 22 ~/.ssh/prod_key "Production server"

# With SSH options
ssh-save prod user@prod.example.com 22 ~/.ssh/prod_key "Production" "-v -o ConnectTimeout=5"

Listing Profiles

ssh-list

Output:

SSH Profiles:
  prod        user@prod.example.com:22 [~/.ssh/prod_key]
  staging     user@staging.example.com:22 [~/.ssh/staging_key]
  dev         user@dev.example.com:2222 [~/.ssh/dev_key]
  backup      user@backup.example.com:22 [default]

Connecting to Profiles

ssh-connect <profile>
# or
ssh <profile>

Fuzzy Search and Connect

sshf

Opens fuzzy selector:

  prod        user@prod.example.com:22
> staging     user@staging.example.com:22
  dev         user@dev.example.com:2222
  backup      user@backup.example.com:22

Select with arrows, press Enter to connect.

Deleting Profiles

ssh-delete <profile>

Syncing Dotfiles to Remote

ssh-sync-dotfiles <profile>

This will:

1. SSH into the remote machine
2. Clone your dotfiles repo
3. Run the installer
4. Validate installation

With custom repo:

ssh-sync-dotfiles prod --repo https://github.com/myuser/dotfiles.git

Quick Reconnect

ssh-reconnect

Reconnects to the last SSH connection.

---

Tmux Workspace Basics

Quick Workspace Access

tw <name>

Creates or attaches to tmux session. If session exists, attaches. If not, creates with default layout.

Creating with Templates

tw-create <name> [template]
tw-create myproject dev
tw-create monitoring ops
tw-create review review

Available Templates:

Template	Layout	Use Case
dev	vim (50%) + terminal (25%) + logs (25%)	Development
ops	4-pane grid	Monitoring
ssh-multi	4 panes (synchronized)	Multi-server ops
debug	2 panes: main (70%), helper (30%)	Debugging
full	Single pane	Fullscreen work
review	Side-by-side panes	Code review

Listing Workspaces

tw-list

Output:

Tmux Workspaces:
  myproject    3 windows, 7 panes
  monitoring   1 window, 4 panes
  ssh-ops      2 windows, 5 panes

Deleting Workspaces

tw-delete <name>

Saving Custom Layout

Current window layout as a reusable template:

tw-save mytemplate

Then use it:

tw-create newproject mytemplate

Fuzzy Workspace Selection

twf

Fuzzy search all tmux sessions and attach.

Pane Synchronization

Send commands to all panes simultaneously:

tw-sync                    # Toggle on/off

When enabled, your typing goes to all panes. Useful for:

• Running same command on multiple servers
• Updating configs in parallel
• Monitoring multiple streams

---

SSH + Tmux Integration

Automatic Tmux Session on SSH

When you connect via ssh-connect, a tmux session is automatically created:

ssh-connect prod
# Creates tmux session: ssh_prod
# Loads ssh_prod template if available
# Attaches you to the session

Session naming: ssh_<profile>

Accessing Your Session

From the remote machine:

# Attach to your session
tmux attach -t ssh_prod

# Detach (leave session running)
Ctrl+B, D

Pre-configured Remote Tmux

If the remote has tmux installed, you can use its features:

# In your SSH session, create new window
Ctrl+B, C

# Navigate windows
Ctrl+B, <number>

Deploy Dotfiles + Setup Tmux Remotely

ssh-sync-dotfiles prod
# Installs dotfiles on remote
# Remote will have same tmux config

---

Workflow Examples

Example 1: Web Development

Setup:

ssh-save staging deploy@staging.example.com 22 ~/.ssh/staging_key

tw-create webdev dev
# Now in tmux with vim ready

Workflow:

Pane 1 (50%): vim/nvim
  - Edit code locally
  
Pane 2 (25%): Dev terminal
  - npm start, python manage.py runserver, etc.
  
Pane 3 (25%): Logs
  - tail -f logs/debug.log

Keybindings:

# Move between panes
Ctrl+B, Left/Right/Up/Down

# Zoom pane
Ctrl+B, Z

# Create new window
Ctrl+B, C

# Switch window
Ctrl+B, 0-9

Example 2: Multi-Server Monitoring

ssh-save web1 ubuntu@web1.prod.com
ssh-save web2 ubuntu@web2.prod.com
ssh-save web3 ubuntu@web3.prod.com

tw-create monitoring ops

Setup in tmux:

# In window, split into 4 panes
Ctrl+B, %           # Split left/right
Ctrl+B, "           # Split top/bottom

# In each pane, open SSH connection
ssh web1
ssh web2
ssh web3
(one more)

# Enable sync for parallel commands
tw-sync

Now you can run commands on all 4 servers simultaneously.

Example 3: Database Backup + Restore

# Save DB server
ssh-save dbserver ubuntu@db.prod.com 22 ~/.ssh/db_key

# Create workspace
tw-create dbops debug

Workflow:

Pane 1 (70%): Main operations
  - mysqldump commands
  - pg_dump commands
  - Restore operations
  
Pane 2 (30%): Helper
  - Monitoring commands
  - Disk space checks
  - Backup status

Example 4: Deployment Pipeline

ssh-save deploy user@deploy.prod.com

tw-create deploy ssh-multi
# Creates 4 synchronized panes

In each pane:

ssh-connect prod      # Pane 1
ssh-connect staging   # Pane 2
ssh-connect dev       # Pane 3
ssh-connect backup    # Pane 4

# Enable sync
tw-sync

# Now run deployment commands on all
./deploy.sh v1.2.3

---

Advanced Features

Custom SSH Options

# Verbose SSH
ssh-save prod user@prod.com 22 ~/.ssh/key "Production" "-v"

# Connection timeout
ssh-save unreliable user@unreliable.com 22 ~/.ssh/key "Unreliable" "-o ConnectTimeout=10"

# Jump host / Bastion
ssh-save internal user@internal.prod.com 22 ~/.ssh/key "Internal" "-o ProxyCommand='ssh -W %h:%p user@bastion.example.com'"

# Multiple options
ssh-save strict user@strict.com 22 ~/.ssh/key "Strict" "-v -o StrictHostKeyChecking=accept-new -o ConnectTimeout=5"

SSH Config Integration

The SSH manager creates entries in ~/.ssh/config. View them:

cat ~/.ssh/config

Example:

Host prod
    HostName prod.example.com
    User ubuntu
    IdentityFile ~/.ssh/prod_key
    Port 22
    ConnectTimeout 10

Use directly:

ssh prod
# Uses the saved profile from SSH config

Batch Operations

Create a script for multi-server operations:

#!/bin/bash
# deploy-to-all.sh

servers=("prod" "staging" "dev")

for server in "${servers[@]}"; do
    echo "Deploying to $server..."
    ssh-connect $server << 'EOF'
        cd /app
        git pull origin main
        ./deploy.sh
        echo "✓ Deployed to $server"
        exit
EOF
done

Run:

chmod +x deploy-to-all.sh
./deploy-to-all.sh

---

Multi-Server Management

Save Multiple Servers

# Web servers
ssh-save web1 ubuntu@web1.prod.com
ssh-save web2 ubuntu@web2.prod.com
ssh-save web3 ubuntu@web3.prod.com

# Database servers
ssh-save db-primary ubuntu@db-primary.prod.com
ssh-save db-replica ubuntu@db-replica.prod.com

# Cache servers
ssh-save redis1 ubuntu@redis1.prod.com
ssh-save redis2 ubuntu@redis2.prod.com

Create Management Workspace

tw-create prod-ops ssh-multi
# Creates workspace with 4 synchronized panes

Connect to All Web Servers

# In 4 panes of the workspace
ssh-connect web1
ssh-connect web2
ssh-connect web3
# (one extra pane)

# Enable sync
tw-sync

# Run command on all
sudo systemctl restart nginx
# Command runs on all 3 web servers

Monitor All Servers

tw-create monitoring ops

# Configure 4 panes for monitoring
# Pane 1: web1 - htop
# Pane 2: web2 - htop
# Pane 3: db-primary - iostat -x 1
# Pane 4: redis1 - redis-cli monitor

Environment-Specific Workspaces

# Production
tw-create prod-dev dev
ssh-sync-dotfiles prod

# Staging
tw-create staging-dev dev
ssh-sync-dotfiles staging

# Development
tw-create dev-local full

---

Troubleshooting

SSH Connection Issues

# Test SSH connection
ssh -vvv <profile>

# View saved connection details
ssh-list

# Delete and re-save
ssh-delete <profile>
ssh-save <profile> <connection> [options]

Tmux Session Issues

# List all tmux sessions
tmux ls

# Kill a session
tmux kill-session -t <name>

# Attach to detached session
tmux attach -t <name>

# Kill all sessions
tmux kill-server

SSH Sync Issues

# Test dotfiles deployment
ssh-sync-dotfiles <profile> --test

# View detailed output
ssh-sync-dotfiles <profile> --verbose

# Deploy specific branch
ssh-sync-dotfiles <profile> --branch develop

Key Permission Issues

# Fix SSH key permissions
chmod 600 ~/.ssh/your_key
chmod 700 ~/.ssh

# List keys
ssh-add -l

# Add key to agent
ssh-add ~/.ssh/your_key

Pane Sync Issues

# Verify sync is enabled
tmux show-window-options synchronize-panes

# Toggle sync manually
Ctrl+B, Shift+X

# Or use script
tw-sync

---

Best Practices

1. Use Descriptive Profile Names

   # Good
   ssh-save prod-web-01 ubuntu@web01.prod.example.com
   ssh-save staging-db ubuntu@db.staging.example.com
   
   # Bad
   ssh-save server1 ubuntu@192.168.1.10
   

2. Store Keys Securely

   chmod 600 ~/.ssh/your_key
   chmod 700 ~/.ssh
   

3. Use SSH Agent

   eval $(ssh-agent)
   ssh-add ~/.ssh/key
   

4. Enable Agent Forwarding for Nested SSH

   ssh-save jumphost user@jump.example.com 22 ~/.ssh/key "" "-A"
   

5. Test Connections

   ssh -T <profile>
   

6. Document Complex Workflows

   # Create README in ~/.dotfiles/ssh-workflows/README.md
   # Document your multi-server setups
   

---

Quick Reference

Command	Purpose
ssh-save	Save SSH profile
ssh-list	List all profiles
ssh-connect	Connect and create tmux session
sshf	Fuzzy search and connect
ssh-delete	Delete profile
ssh-sync-dotfiles	Deploy dotfiles to remote
tw	Quick workspace attach/create
tw-create	Create workspace with template
tw-list	List all workspaces
tw-delete	Delete workspace
tw-save	Save current layout as template
tw-sync	Toggle pane synchronization
twf	Fuzzy select workspace
ssh-reconnect	Quick reconnect to last SSH

---

For more information on individual features, see:

• README.md - Main documentation
• SETUP_GUIDE.md - Installation and basic configuration