Sanitized mirror from private repository - 2026-03-10 09:13:26 UTC
This commit is contained in:
Gitea Mirror Bot
361
docs/infrastructure/SSH_ACCESS_GUIDE.md
Normal file
361
docs/infrastructure/SSH_ACCESS_GUIDE.md
Normal file
@@ -0,0 +1,361 @@
|
||||
# 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.*
|
||||
Reference in New Issue
Block a user