# SSH + Tmux Integration Guide

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

## Table of Contents

- [SSH Manager Overview](#ssh-manager-overview)
- [Basic SSH Management](#basic-ssh-management)
- [Tmux Workspace Basics](#tmux-workspace-basics)
- [SSH + Tmux Integration](#ssh--tmux-integration)
- [Workflow Examples](#workflow-examples)
- [Advanced Features](#advanced-features)
- [Multi-Server Management](#multi-server-management)
- [Troubleshooting](#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

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

**Examples:**

```bash
# 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

```bash
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

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

### Fuzzy Search and Connect

```bash
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

```bash
ssh-delete <profile>
```

### Syncing Dotfiles to Remote

```bash
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:**

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

### Quick Reconnect

```bash
ssh-reconnect
```

Reconnects to the last SSH connection.

---

## Tmux Workspace Basics

### Quick Workspace Access

```bash
tw <name>
```

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

### Creating with Templates

```bash
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

```bash
tw-list
```

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

### Deleting Workspaces

```bash
tw-delete <name>
```

### Saving Custom Layout

Current window layout as a reusable template:

```bash
tw-save mytemplate
```

Then use it:

```bash
tw-create newproject mytemplate
```

### Fuzzy Workspace Selection

```bash
twf
```

Fuzzy search all tmux sessions and attach.

### Pane Synchronization

Send commands to all panes simultaneously:

```bash
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:

```bash
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:

```bash
# 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:

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

# Navigate windows
Ctrl+B, <number>
```

### Deploy Dotfiles + Setup Tmux Remotely

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

---

## Workflow Examples

### Example 1: Web Development

**Setup:**

```bash
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:**

```bash
# 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

```bash
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:**

```bash
# 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

```bash
# 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

```bash
ssh-save deploy user@deploy.prod.com

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

**In each pane:**

```bash
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

```bash
# 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:

```bash
cat ~/.ssh/config
```

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

Use directly:

```bash
ssh prod
# Uses the saved profile from SSH config
```

### Batch Operations

Create a script for multi-server operations:

```bash
#!/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:

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

---

## Multi-Server Management

### Save Multiple Servers

```bash
# 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

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

### Connect to All Web Servers

```bash
# 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

```bash
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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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**
   ```bash
   # 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**
   ```bash
   chmod 600 ~/.ssh/your_key
   chmod 700 ~/.ssh
   ```

3. **Use SSH Agent**
   ```bash
   eval $(ssh-agent)
   ssh-add ~/.ssh/key
   ```

4. **Enable Agent Forwarding for Nested SSH**
   ```bash
   ssh-save jumphost user@jump.example.com 22 ~/.ssh/key "" "-A"
   ```

5. **Test Connections**
   ```bash
   ssh -T <profile>
   ```

6. **Document Complex Workflows**
   ```bash
   # 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](../README.md) - Main documentation
- [SETUP_GUIDE.md](SETUP_GUIDE.md) - Installation and basic configuration