tinyboard/README.md

# TinyBoard

A hub-spoke architecture for secure file sharing over SSH tunnels using autossh and rclone.

Spokes are ARM devices (e.g. OrangePi, Raspberry Pi) running Armbian that establish reverse SSH tunnels to a central hub server. The hub mounts spoke filesystems via SFTP using rclone, making files accessible across all devices without exposing them to the internet.

---

## Quickstart

### Setting up a new Hub

On a fresh Debian/Ubuntu VPS or server:

```bash
apt install git
git clone https://gut.oily.dad/justin/tinyboard
cd tinyboard
./setup.sh   # choose option 4
```

### Setting up a new Spoke

On a fresh Armbian device:

1. Modify `spoke/armbian.not_logged_in_yet` accordingly, then drop it onto the SD card as `/root/.not_logged_in_yet` before first boot (WiFi credentials) — see [Armbian Autoconfig docs](https://docs.armbian.com/User-Guide_Autoconfig/)
2. Boot, SSH in as root
3. Run:

```bash
apt install git
git clone https://gut.oily.dad/justin/tinyboard
cd tinyboard
./spoke/setup-network.sh   # configure static IP — SSH session will drop, reconnect
./setup.sh           # choose option 1
```

### Onboarding a Spoke from the Hub

Once the spoke tunnel is up, run on the hub:

```bash
cd tinyboard
./setup.sh   # choose option 2
```

### Offboarding a Spoke from the Hub

```bash
cd tinyboard
./setup.sh   # choose option 3
```

---

## Architecture

```
  [ Spoke ]                        [ Hub ]
  OrangePi / RPi                   VPS / Server
  Armbian                          Any Linux

  autossh container  ──────────►  sshd (GatewayPorts)
  reverse tunnel                   port 111xx

                                   rclone SFTP mount
                                   ~/mnt/<spoke-name>/
```

Spokes initiate outbound SSH connections to the hub, creating reverse tunnels. The hub then uses rclone to mount each spoke's filesystem over SFTP through the tunnel. No inbound ports need to be open on the spoke.

---

## Directory Structure

```
tinyboard/
├── setup.sh                  ← entry point
├── spoke/
│   ├── setup-network.sh      ← configure static IP before setup
│   ├── setup-spoke.sh        ← automated spoke setup
│   ├── compose.yaml          ← Docker Compose for autossh + syncthing
│   ├── Dockerfile            ← autossh container
│   └── armbian.not_logged_in_yet ← Armbian first-boot WiFi config template
└── hub/
    ├── setup-hub.sh          ← automated hub setup
    ├── onboard-spoke.sh      ← add a new spoke to the hub
    └── offboard-spoke.sh     ← remove a spoke from the hub
```

---

## Setup Scripts

### `setup.sh`
Entry point. Presents a menu:
1. Set up this device as a new spoke
2. Onboard a new spoke from the hub
3. Offboard a spoke from the hub
4. Set up this device as a new hub

### `spoke/setup-network.sh`
Run as root on a new spoke before `setup.sh`. Configures a static IP via netplan. Supports both WiFi and wired interfaces. Automatically reverts if network connectivity is lost after applying the new config.

### `spoke/setup-spoke.sh`
Run as root on a new spoke. Handles:
- Package installation (apt/dnf/yum/pacman)
- Docker installation
- SSH server setup
- Hostname configuration
- SSH key generation and hub authorization
- Tunnel port auto-detection on the hub
- Docker image build and container start
- Optional password auth disable

### `hub/setup-hub.sh`
Run as root on a new hub server. Handles:
- Package installation (apt/dnf/yum/pacman)
- rclone installation
- Hub user creation
- SSH server configuration (GatewayPorts, AllowTcpForwarding)
- FUSE configuration
- rclone config directory setup
- Optional password auth disable

### `hub/onboard-spoke.sh`
Run as the hub user after a spoke connects. Handles:
- SSH key generation and deployment to spoke
- rclone remote configuration
- Spoke registration in `~/.config/tinyboard/spokes`
- Per-spoke crontab entry for auto-mount on reboot

### `hub/offboard-spoke.sh`
Run as the hub user to remove a spoke. Handles:
- Unmounting the spoke filesystem
- Removing the crontab entry
- Removing the rclone remote
- Optionally removing the hub SSH key
- Removing from the spoke registry

---

## Spoke Registry

The hub maintains a registry of connected spokes at `~/.config/tinyboard/spokes`:

```
rocky  11113  /home/armbian/.ssh/armbian-rocky-202504  /home/armbian/mnt/rocky
gouda  11114  /home/armbian/.ssh/armbian-gouda-202504  /home/armbian/mnt/gouda
```

Each spoke gets its own mount point at `~/mnt/<spoke-name>/` and a dedicated rclone crontab entry.

---

## Security

- All communication is over SSH tunnels — no spoke ports exposed to the internet
- SSH keys are used for all authentication
- Scripts check and auto-fix unsafe file permissions (600/400)
- Password authentication can be disabled during setup
- Scripts refuse to disable password auth if no authorized keys are present (lockout prevention)
- Netplan changes are verified with a 30-second connectivity check before being made permanent

---

## Sensitive Files

Before committing, ensure the following do not contain real credentials:

- `spoke/armbian.not_logged_in_yet` — contains WiFi SSID, password, and user passwords

---

## Troubleshooting

### `apt update` fails with beta.armbian.com error

On some Armbian images, a beta apt repository is enabled by default and may cause `apt update` to fail. Comment it out:

```bash
grep -r "beta.armbian" /etc/apt/sources.list /etc/apt/sources.list.d/
```

Open the file that contains it (usually `/etc/apt/sources.list.d/armbian.sources`) and comment out or remove the line referencing `beta.armbian.com`, then run `apt update` again.

---

## Requirements

**Spoke:** Armbian (Debian-based), ARM device, Docker, autossh, git

**Hub:** Any Linux server (Debian/Ubuntu/RHEL/Arch), rclone, fuse, openssh-server