406 lines
8.5 KiB
Markdown
406 lines
8.5 KiB
Markdown
# VS Code SSH Setup for TrueNAS
|
|
|
|
## Overview
|
|
|
|
Configure VS Code to SSH into your TrueNAS server for easy file editing and terminal access.
|
|
|
|
---
|
|
|
|
## Prerequisites
|
|
|
|
1. **VS Code installed** on your local machine
|
|
2. **Remote - SSH extension** installed in VS Code
|
|
3. **SSH access enabled** on TrueNAS
|
|
4. **TrueNAS IP address** or hostname
|
|
|
|
---
|
|
|
|
## Step 1: Install VS Code Extension
|
|
|
|
### Install Remote - SSH Extension
|
|
|
|
1. Open VS Code
|
|
2. Click Extensions icon (or `Ctrl+Shift+X`)
|
|
3. Search for: **Remote - SSH**
|
|
4. Install the extension by Microsoft
|
|
5. Reload VS Code if prompted
|
|
|
|
**Extension ID:** `ms-vscode-remote.remote-ssh`
|
|
|
|
---
|
|
|
|
## Step 2: Enable SSH on TrueNAS (if not already enabled)
|
|
|
|
### TrueNAS Scale
|
|
|
|
1. Navigate to **System Settings → Services**
|
|
2. Find **SSH** service
|
|
3. Click **Edit** (pencil icon)
|
|
4. Configure:
|
|
- ☑ **Allow Password Authentication** (initially, we'll use keys later)
|
|
- ☑ **Allow TCP Forwarding**
|
|
- Port: **22** (default)
|
|
5. Click **Save**
|
|
6. **Start** the SSH service
|
|
7. ☑ **Start Automatically** (enable)
|
|
|
|
---
|
|
|
|
## Step 3: Find Your TrueNAS Connection Details
|
|
|
|
### Get TrueNAS IP Address
|
|
|
|
**Option A: From TrueNAS UI**
|
|
- Dashboard → Top right shows IP address
|
|
|
|
**Option B: From Shell**
|
|
```bash
|
|
ip addr show | grep inet
|
|
```
|
|
|
|
### Get Your Username
|
|
|
|
**Default admin user:** `admin`
|
|
|
|
Or check: **Credentials → Local Users**
|
|
|
|
---
|
|
|
|
## Step 4: Generate SSH Key (Recommended)
|
|
|
|
**On your local Windows machine (WSL or PowerShell):**
|
|
|
|
### Using WSL (Recommended)
|
|
|
|
```bash
|
|
# Generate SSH key
|
|
ssh-keygen -t ed25519 -C "truenas-access"
|
|
|
|
# Default location: ~/.ssh/id_ed25519
|
|
# Press Enter to accept
|
|
# Enter passphrase (optional but recommended)
|
|
|
|
# Copy public key to TrueNAS
|
|
ssh-copy-id admin@truenas-ip
|
|
|
|
# Or manually copy:
|
|
cat ~/.ssh/id_ed25519.pub
|
|
# Then paste into TrueNAS UI
|
|
```
|
|
|
|
### Using PowerShell (Alternative)
|
|
|
|
```powershell
|
|
# Generate SSH key
|
|
ssh-keygen -t ed25519 -C "truenas-access"
|
|
|
|
# Location: C:\Users\Vince\.ssh\id_ed25519
|
|
# Copy public key
|
|
Get-Content C:\Users\Vince\.ssh\id_ed25519.pub
|
|
```
|
|
|
|
### Add Public Key to TrueNAS
|
|
|
|
1. TrueNAS UI → **Credentials → Local Users**
|
|
2. Click **Edit** on your user (admin)
|
|
3. Scroll to **SSH Public Key**
|
|
4. Paste your public key
|
|
5. Click **Save**
|
|
|
|
---
|
|
|
|
## Step 5: Configure SSH Config File
|
|
|
|
Create/edit SSH config for easy connections.
|
|
|
|
### Location
|
|
|
|
**WSL:** `~/.ssh/config`
|
|
**Windows:** `C:\Users\Vince\.ssh\config`
|
|
|
|
### Add TrueNAS Configuration
|
|
|
|
```bash
|
|
Host truenas
|
|
HostName 192.168.1.XXX # Your TrueNAS IP
|
|
User admin # Your TrueNAS username
|
|
Port 22
|
|
IdentityFile ~/.ssh/id_ed25519 # Path to your SSH key
|
|
ForwardAgent yes
|
|
ServerAliveInterval 60
|
|
ServerAliveCountMax 3
|
|
|
|
# Optional: Shorter alias
|
|
Host nas
|
|
HostName 192.168.1.XXX
|
|
User admin
|
|
IdentityFile ~/.ssh/id_ed25519
|
|
```
|
|
|
|
**Replace:** `192.168.1.XXX` with your actual TrueNAS IP
|
|
|
|
### Test SSH Connection
|
|
|
|
```bash
|
|
ssh truenas
|
|
# or
|
|
ssh nas
|
|
```
|
|
|
|
Should connect without password!
|
|
|
|
---
|
|
|
|
## Step 6: Connect VS Code to TrueNAS
|
|
|
|
### Method 1: Using Command Palette
|
|
|
|
1. Open VS Code
|
|
2. Press `Ctrl+Shift+P` (or `F1`)
|
|
3. Type: **Remote-SSH: Connect to Host**
|
|
4. Select **truenas** (or **nas**) from the list
|
|
- Or type: `admin@truenas-ip` manually
|
|
5. Select platform: **Linux**
|
|
6. VS Code will connect and install VS Code Server on TrueNAS
|
|
7. Wait for connection to complete
|
|
|
|
### Method 2: Using SSH Targets
|
|
|
|
1. Click **Remote Explorer** icon in sidebar
|
|
2. Under **SSH Targets**, you'll see configured hosts
|
|
3. Click **→** (Connect) next to **truenas**
|
|
|
|
### First Connection
|
|
|
|
- VS Code will install **VS Code Server** on TrueNAS (~100MB)
|
|
- This is a one-time setup
|
|
- May take 1-2 minutes
|
|
- You'll see progress in bottom right
|
|
|
|
---
|
|
|
|
## Step 7: Navigate to Your Stacks Directory
|
|
|
|
Once connected:
|
|
|
|
1. **File → Open Folder**
|
|
2. Type: `/mnt/tank/stacks`
|
|
3. Click **OK**
|
|
4. VS Code now shows your stacks directory in explorer!
|
|
|
|
---
|
|
|
|
## Step 8: Install Helpful Extensions (Remote)
|
|
|
|
Once connected to TrueNAS, install these extensions **on the remote**:
|
|
|
|
### Recommended Extensions
|
|
|
|
1. **Docker** (`ms-azuretools.vscode-docker`)
|
|
- Syntax highlighting for docker-compose files
|
|
- Docker commands integration
|
|
|
|
2. **YAML** (`redhat.vscode-yaml`)
|
|
- YAML syntax validation
|
|
- Auto-completion
|
|
|
|
3. **Remote - SSH: Editing Configuration Files** (automatic)
|
|
- Edit SSH config directly from VS Code
|
|
|
|
### Install Extensions on Remote
|
|
|
|
1. Click **Extensions** icon
|
|
2. Search for extension
|
|
3. Click **Install in SSH: truenas**
|
|
4. Extensions install on the TrueNAS server
|
|
|
|
---
|
|
|
|
## Usage Tips
|
|
|
|
### Open Terminal in VS Code
|
|
|
|
- **Terminal → New Terminal** (`` Ctrl+` ``)
|
|
- Opens bash terminal directly on TrueNAS
|
|
- Already in the folder you have open
|
|
|
|
### Edit docker-compose Files
|
|
|
|
1. Navigate to `/mnt/tank/stacks/traefik/`
|
|
2. Edit `docker-compose.yml`
|
|
3. Syntax highlighting and validation included
|
|
4. Save with `Ctrl+S`
|
|
|
|
### Run Docker Commands
|
|
|
|
```bash
|
|
# In VS Code terminal
|
|
cd /mnt/tank/stacks/traefik
|
|
docker compose up -d
|
|
docker logs traefik -f
|
|
```
|
|
|
|
### Multiple Folders
|
|
|
|
Open workspace with multiple stack directories:
|
|
1. **File → Add Folder to Workspace**
|
|
2. Add `/mnt/tank/stacks/traefik`
|
|
3. Add `/mnt/tank/stacks/gitea`
|
|
4. Add `/mnt/tank/stacks/servarr`
|
|
5. **File → Save Workspace As** → `truenas-stacks.code-workspace`
|
|
|
|
---
|
|
|
|
## Troubleshooting
|
|
|
|
### Connection Refused
|
|
|
|
```bash
|
|
# Check SSH service is running on TrueNAS
|
|
# TrueNAS UI → System → Services → SSH → Running
|
|
|
|
# Test from terminal
|
|
ssh admin@truenas-ip
|
|
```
|
|
|
|
### Permission Denied (publickey)
|
|
|
|
```bash
|
|
# Verify public key is added to TrueNAS
|
|
# TrueNAS UI → Credentials → Local Users → Edit → SSH Public Key
|
|
|
|
# Or enable password authentication temporarily
|
|
# TrueNAS UI → System → Services → SSH → Edit
|
|
# ☑ Allow Password Authentication
|
|
```
|
|
|
|
### VS Code Server Installation Fails
|
|
|
|
```bash
|
|
# SSH into TrueNAS manually
|
|
ssh truenas
|
|
|
|
# Check available disk space
|
|
df -h
|
|
|
|
# VS Code Server needs ~100MB in home directory
|
|
# Clear space if needed
|
|
```
|
|
|
|
### "Could not establish connection"
|
|
|
|
```bash
|
|
# Check VS Code settings
|
|
# Ctrl+, → Search "remote.SSH.path"
|
|
# Should point to ssh executable
|
|
|
|
# Windows: C:\Windows\System32\OpenSSH\ssh.exe
|
|
# WSL: /usr/bin/ssh
|
|
```
|
|
|
|
### Wrong Platform Detected
|
|
|
|
If VS Code thinks TrueNAS is Windows/Mac:
|
|
1. `Ctrl+Shift+P`
|
|
2. **Remote-SSH: Settings**
|
|
3. Add to `settings.json`:
|
|
```json
|
|
"remote.SSH.remotePlatform": {
|
|
"truenas": "linux"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Security Best Practices
|
|
|
|
### Disable Password Authentication (After Key Setup)
|
|
|
|
Once SSH keys are working:
|
|
|
|
1. TrueNAS UI → **System → Services → SSH → Edit**
|
|
2. ☐ **Allow Password Authentication** (uncheck)
|
|
3. ☑ **Login as Root with Password** (uncheck)
|
|
4. Click **Save**
|
|
|
|
Now only SSH key authentication is allowed.
|
|
|
|
### Use SSH Key Passphrase
|
|
|
|
When generating keys, add a passphrase:
|
|
```bash
|
|
ssh-keygen -t ed25519 -C "truenas-access"
|
|
# Enter passphrase when prompted
|
|
```
|
|
|
|
Use `ssh-agent` to avoid typing passphrase repeatedly:
|
|
```bash
|
|
# Start ssh-agent (WSL)
|
|
eval "$(ssh-agent -s)"
|
|
|
|
# Add key
|
|
ssh-add ~/.ssh/id_ed25519
|
|
|
|
# Enter passphrase once
|
|
# Key is cached for session
|
|
```
|
|
|
|
### Firewall Considerations
|
|
|
|
If accessing TrueNAS from outside your network:
|
|
- **Don't expose SSH (port 22) directly to internet**
|
|
- Use VPN (Tailscale, Wireguard) instead
|
|
- Or use SSH tunneling through a bastion host
|
|
|
|
---
|
|
|
|
## Quick Reference
|
|
|
|
### Connect to TrueNAS
|
|
|
|
```bash
|
|
# Command line
|
|
ssh truenas
|
|
|
|
# VS Code
|
|
Ctrl+Shift+P → Remote-SSH: Connect to Host → truenas
|
|
```
|
|
|
|
### Common Paths
|
|
|
|
- **Stacks:** `/mnt/tank/stacks/`
|
|
- **Configs:** `/mnt/tank/configs/`
|
|
- **Media:** `/mnt/tank/media/`
|
|
|
|
### Useful VS Code Shortcuts
|
|
|
|
- **Open Terminal:** `` Ctrl+` ``
|
|
- **Command Palette:** `Ctrl+Shift+P`
|
|
- **Open Folder:** `Ctrl+K Ctrl+O`
|
|
- **Search Files:** `Ctrl+P`
|
|
- **Save:** `Ctrl+S`
|
|
- **Close Remote:** Click **SSH: truenas** in bottom left → **Close Remote Connection**
|
|
|
|
---
|
|
|
|
## Next Steps
|
|
|
|
- [ ] Install Remote - SSH extension in VS Code
|
|
- [ ] Enable SSH service on TrueNAS
|
|
- [ ] Generate SSH key on local machine
|
|
- [ ] Add public key to TrueNAS
|
|
- [ ] Configure ~/.ssh/config with TrueNAS host
|
|
- [ ] Test SSH connection from terminal
|
|
- [ ] Connect VS Code to TrueNAS
|
|
- [ ] Open `/mnt/tank/stacks` folder in VS Code
|
|
- [ ] Install Docker and YAML extensions (remote)
|
|
- [ ] Disable password authentication (after key setup)
|
|
- [ ] Create workspace for multiple stack folders
|
|
|
|
---
|
|
|
|
## Resources
|
|
|
|
- [VS Code Remote - SSH Documentation](https://code.visualstudio.com/docs/remote/ssh)
|
|
- [TrueNAS Scale SSH Documentation](https://www.truenas.com/docs/scale/scaletutorials/systemsettings/services/configuringsshservice/)
|