361 lines
6.9 KiB
Markdown
361 lines
6.9 KiB
Markdown
# SSH Access Guide for Homelab
|
|
|
|
This guide helps you set up secure SSH access to your homelab servers for deployment and management.
|
|
|
|
## 🎯 Overview
|
|
|
|
SSH access allows you to:
|
|
- **Deploy services directly** on servers
|
|
- **Troubleshoot issues** in real-time
|
|
- **Manage configurations** remotely
|
|
- **Transfer files** securely
|
|
- **Monitor services** and logs
|
|
|
|
## 🔑 Setting Up SSH Access
|
|
|
|
### Step 1: Generate SSH Key Pair
|
|
|
|
**On your local machine:**
|
|
|
|
```bash
|
|
# Generate a new SSH key (recommended: Ed25519)
|
|
ssh-keygen -t ed25519 -f ~/.ssh/homelab_key -C "your-email@example.com"
|
|
|
|
# Or use RSA if Ed25519 isn't supported
|
|
ssh-keygen -t rsa -b 4096 -f ~/.ssh/homelab_key -C "your-email@example.com"
|
|
|
|
# Set proper permissions
|
|
chmod 600 ~/.ssh/homelab_key
|
|
chmod 644 ~/.ssh/homelab_key.pub
|
|
```
|
|
|
|
### Step 2: Copy Public Key to Servers
|
|
|
|
**For each server in your homelab:**
|
|
|
|
```bash
|
|
# Copy public key to server (replace with your server details)
|
|
ssh-copy-id -i ~/.ssh/homelab_key.pub username@server-ip
|
|
|
|
# Or manually copy if ssh-copy-id isn't available
|
|
cat ~/.ssh/homelab_key.pub | ssh username@server-ip "mkdir -p ~/.ssh && cat >> ~/.ssh/authorized_keys"
|
|
```
|
|
|
|
### Step 3: Configure SSH Client
|
|
|
|
Create an SSH config file for easy access:
|
|
|
|
```bash
|
|
# Create/edit SSH config
|
|
nano ~/.ssh/config
|
|
```
|
|
|
|
**Add your homelab servers:**
|
|
|
|
```bash
|
|
# ~/.ssh/config
|
|
|
|
# Main Synology NAS (Atlantis)
|
|
Host atlantis
|
|
HostName 192.168.1.100
|
|
User admin
|
|
IdentityFile ~/.ssh/homelab_key
|
|
Port 22
|
|
ServerAliveInterval 60
|
|
|
|
# Secondary Synology NAS (Calypso)
|
|
Host calypso
|
|
HostName 192.168.1.101
|
|
User admin
|
|
IdentityFile ~/.ssh/homelab_key
|
|
Port 22
|
|
ServerAliveInterval 60
|
|
|
|
# Primary VM (Homelab VM)
|
|
Host homelab-vm
|
|
HostName 192.168.1.110
|
|
User ubuntu
|
|
IdentityFile ~/.ssh/homelab_key
|
|
Port 22
|
|
ServerAliveInterval 60
|
|
|
|
# Physical NUC (Concord)
|
|
Host concord-nuc
|
|
HostName 192.168.1.120
|
|
User ubuntu
|
|
IdentityFile ~/.ssh/homelab_key
|
|
Port 22
|
|
ServerAliveInterval 60
|
|
|
|
# Raspberry Pi (Edge device)
|
|
Host rpi5-vish
|
|
HostName 192.168.1.130
|
|
User pi
|
|
IdentityFile ~/.ssh/homelab_key
|
|
Port 22
|
|
ServerAliveInterval 60
|
|
```
|
|
|
|
**Set proper permissions:**
|
|
```bash
|
|
chmod 600 ~/.ssh/config
|
|
```
|
|
|
|
### Step 4: Test Connections
|
|
|
|
```bash
|
|
# Test connection to each server
|
|
ssh atlantis
|
|
ssh calypso
|
|
ssh homelab-vm
|
|
ssh concord-nuc
|
|
ssh rpi5-vish
|
|
```
|
|
|
|
## 🚀 SSH-Based Deployment Workflow
|
|
|
|
### Method 1: Direct Docker Compose Deployment
|
|
|
|
```bash
|
|
# Connect to target server
|
|
ssh atlantis
|
|
|
|
# Navigate to docker directory
|
|
cd /volume1/docker
|
|
|
|
# Create service directory
|
|
mkdir my-new-service
|
|
cd my-new-service
|
|
|
|
# Create docker-compose.yml
|
|
nano docker-compose.yml
|
|
|
|
# Deploy the service
|
|
docker compose up -d
|
|
|
|
# Check status
|
|
docker compose ps
|
|
```
|
|
|
|
### Method 2: Git-Based Deployment
|
|
|
|
```bash
|
|
# Connect to server
|
|
ssh homelab-vm
|
|
|
|
# Clone/update repository
|
|
git clone https://git.vish.gg/Vish/homelab.git
|
|
cd homelab
|
|
|
|
# Deploy specific service
|
|
docker compose -f hosts/vms/homelab-vm/my-service.yml up -d
|
|
```
|
|
|
|
### Method 3: Remote File Transfer
|
|
|
|
```bash
|
|
# Copy compose file to server
|
|
scp hosts/synology/atlantis/my-service.yml atlantis:/volume1/docker/
|
|
|
|
# Connect and deploy
|
|
ssh atlantis
|
|
cd /volume1/docker
|
|
docker compose -f my-service.yml up -d
|
|
```
|
|
|
|
## 🛠️ Common SSH Tasks for Homelab
|
|
|
|
### Service Management
|
|
|
|
```bash
|
|
# Check running containers
|
|
ssh atlantis "docker ps"
|
|
|
|
# View service logs
|
|
ssh atlantis "docker compose -f /volume1/docker/service/docker-compose.yml logs -f"
|
|
|
|
# Restart a service
|
|
ssh atlantis "docker compose -f /volume1/docker/service/docker-compose.yml restart"
|
|
|
|
# Update and restart service
|
|
ssh atlantis "cd /volume1/docker/service && docker compose pull && docker compose up -d"
|
|
```
|
|
|
|
### System Monitoring
|
|
|
|
```bash
|
|
# Check system resources
|
|
ssh homelab-vm "htop"
|
|
ssh homelab-vm "df -h"
|
|
ssh homelab-vm "free -h"
|
|
|
|
# Check Docker status
|
|
ssh atlantis "docker system df"
|
|
ssh atlantis "docker system prune -f"
|
|
```
|
|
|
|
### File Management
|
|
|
|
```bash
|
|
# Copy files to server
|
|
scp local-file.txt atlantis:/volume1/docker/service/
|
|
|
|
# Copy files from server
|
|
scp atlantis:/volume1/docker/service/config.yml ./
|
|
|
|
# Sync directories
|
|
rsync -avz --progress ./local-dir/ atlantis:/volume1/docker/service/
|
|
```
|
|
|
|
## 🔒 Security Best Practices
|
|
|
|
### SSH Key Security
|
|
|
|
```bash
|
|
# Use SSH agent for key management
|
|
eval "$(ssh-agent -s)"
|
|
ssh-add ~/.ssh/homelab_key
|
|
|
|
# List loaded keys
|
|
ssh-add -l
|
|
|
|
# Remove keys from agent
|
|
ssh-add -D
|
|
```
|
|
|
|
### Server Hardening
|
|
|
|
**On each server, consider:**
|
|
|
|
```bash
|
|
# Disable password authentication (after key setup)
|
|
sudo nano /etc/ssh/sshd_config
|
|
# Set: PasswordAuthentication no
|
|
# Set: PubkeyAuthentication yes
|
|
|
|
# Restart SSH service
|
|
sudo systemctl restart sshd
|
|
|
|
# Change default SSH port (optional)
|
|
# Set: Port 2222
|
|
|
|
# Limit SSH access to specific users
|
|
# Set: AllowUsers yourusername
|
|
```
|
|
|
|
### Firewall Configuration
|
|
|
|
```bash
|
|
# Allow SSH through firewall
|
|
sudo ufw allow ssh
|
|
# Or for custom port:
|
|
sudo ufw allow 2222/tcp
|
|
|
|
# Enable firewall
|
|
sudo ufw enable
|
|
```
|
|
|
|
## 🚨 Troubleshooting SSH Issues
|
|
|
|
### Connection Problems
|
|
|
|
```bash
|
|
# Debug connection with verbose output
|
|
ssh -vvv atlantis
|
|
|
|
# Test specific port
|
|
ssh -p 22 atlantis
|
|
|
|
# Check if SSH service is running
|
|
ssh atlantis "sudo systemctl status sshd"
|
|
```
|
|
|
|
### Permission Issues
|
|
|
|
```bash
|
|
# Fix SSH directory permissions
|
|
chmod 700 ~/.ssh
|
|
chmod 600 ~/.ssh/id_*
|
|
chmod 644 ~/.ssh/id_*.pub
|
|
chmod 600 ~/.ssh/config
|
|
chmod 600 ~/.ssh/authorized_keys
|
|
```
|
|
|
|
### Key Issues
|
|
|
|
```bash
|
|
# Remove old host key (if server changed)
|
|
ssh-keygen -R atlantis
|
|
ssh-keygen -R 192.168.1.100
|
|
|
|
# Test key authentication
|
|
ssh -i ~/.ssh/homelab_key -o PreferredAuthentications=publickey atlantis
|
|
```
|
|
|
|
## 📋 Quick Reference
|
|
|
|
### SSH Config Template
|
|
|
|
```bash
|
|
Host HOSTNAME
|
|
HostName IP_ADDRESS
|
|
User USERNAME
|
|
IdentityFile ~/.ssh/homelab_key
|
|
Port 22
|
|
ServerAliveInterval 60
|
|
ServerAliveCountMax 3
|
|
ConnectTimeout 10
|
|
```
|
|
|
|
### Common Commands
|
|
|
|
```bash
|
|
# Connect to server
|
|
ssh hostname
|
|
|
|
# Execute single command
|
|
ssh hostname "command"
|
|
|
|
# Copy files
|
|
scp file hostname:/path/
|
|
scp hostname:/path/file ./
|
|
|
|
# Port forwarding (access remote service locally)
|
|
ssh -L 8080:localhost:8080 hostname
|
|
|
|
# Background tunnel
|
|
ssh -f -N -L 8080:localhost:8080 hostname
|
|
```
|
|
|
|
### Server-Specific Paths
|
|
|
|
- **Synology NAS**: `/volume1/docker/`
|
|
- **Ubuntu VMs**: `/home/username/docker/` or `/opt/docker/`
|
|
- **Raspberry Pi**: `/home/pi/docker/`
|
|
|
|
## 🔗 Integration with Development Workflow
|
|
|
|
### Combined Git + SSH Workflow
|
|
|
|
```bash
|
|
# 1. Develop locally with validation
|
|
git add hosts/synology/atlantis/my-service.yml
|
|
git commit -m "feat: Add my-service"
|
|
git push
|
|
|
|
# 2. Deploy via SSH
|
|
ssh atlantis
|
|
cd /volume1/docker
|
|
git pull
|
|
docker compose -f ../homelab/hosts/synology/atlantis/my-service.yml up -d
|
|
|
|
# 3. Monitor deployment
|
|
docker compose ps
|
|
docker compose logs -f my-service
|
|
```
|
|
|
|
This gives you the best of both worlds: validated configurations and direct deployment control.
|
|
|
|
---
|
|
|
|
*With SSH access configured, you have full control over your homelab infrastructure while maintaining the safety of the GitOps workflow.* |