tinyboard/README.md

TinyBoard Hub-Spoke File Sharing System

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

Architecture Overview

This system implements a hub-and-spoke model where:

• Spokes: Raspberry Pi devices running Armbian that establish reverse SSH tunnels to the hub
• Hub: Central server that mounts spoke filesystems via SFTP using rclone

Key Components

1. Spoke Side (spoke/ directory):

   • Docker-based autossh tunnel container
   • Configuration files for spoke setup
   • Hostname assignment based on MAC address

2. Hub Side (hub/ directory):

   • Rclone SFTP mount configuration
   • Systemd user service for automatic mounting

3. Management Script (hubspoke-helper.sh):

   • Unified interface for managing both hub and spoke components

Directory Structure

tinyboard/
├── hubspoke-helper.sh          # Main management script
├── hub/
│   └── rclone.conf             # Rclone SFTP configuration
├── spoke/
│   ├── compose.yaml            # Docker Compose for autossh tunnel
│   ├── Dockerfile              # autossh container image
│   ├── autohostname.sh         # Hostname assignment by MAC address
│   ├── aptprimary.sh           # Initial package installation
│   ├── clean_sensitive.sh      # Clean WiFi/password from configs
│   └── armb-not_logged_in_yet  # Armbian first-boot configuration
└── README.md                   # This file

Key File Handling (Manual Setup)

IMPORTANT: The following files must be manually created/configured as they contain sensitive information:

SSH Keys

• ~/.ssh/oilykey2026 on spokes (referenced in spoke/compose.yaml)
• ~/.ssh/armbian-brie-202604 on hub (referenced in hub/rclone.conf)
• These keys must be manually generated and distributed

Rclone Configuration

• ~/.config/rclone/rclone.conf on hub must be manually created
• Use hub/rclone.conf as a template
• Update host, port, and key_file paths as needed
• Manually create rclone mount and permission it (/mnt/hub for example)

Systemd Service Files

• ~/.config/systemd/user/rclone-mount@.service must be manually copied from hub/rclone-mount@.service

Spoke Setup (Raspberry Pi / Armbian)

Initial Setup

1. Write Armbian minimal image to SD card
2. Copy spoke/armb-not_logged_in_yet to SD card root /root/.not_logged_in_yet (contains WiFi credentials)
3. Boot device, SSH in as root with password "1234"
4. After first login and setup tasks, .not_logged_in_yet will be processed for root and armbian user credentials
5. Clone this repository: git clone <repo-url>
6. Run spoke/aptprimary.sh to install required packages
7. Run spoke/autohostname.sh to assign hostname based on MAC address
8. Reboot and test as armbian user

SSH Key Setup

1. Generate SSH key pair on hub: ssh-keygen -t ed25519 -f ~/.ssh/armbian-brie-202604
2. Copy public key to spoke: ssh-copy-id -i ~/.ssh/armbian-brie-202604.pub armbian@<spoke-ip>
3. Generate spoke key: ssh-keygen -t ed25519 -f ~/.ssh/oilykey2026
4. Copy public key to hub for reverse tunnel authentication

Docker Tunnel Setup

# Build the autossh container
./hubspoke-helper.sh spoke build

# Start the tunnel
./hubspoke-helper.sh spoke start

# Check status
./hubspoke-helper.sh spoke status

# View logs
./hubspoke-helper.sh spoke logs

Hub Setup (Central Server)

Rclone Configuration

1. Install rclone: apt install rclone fuse
2. Create config directory: mkdir -p ~/.config/rclone
3. Copy and customize hub/rclone.conf to ~/.config/rclone/rclone.conf
4. Update key_file path to point to your SSH private key

FUSE Configuration

# Allow other users to access mounts (if needed)
sudo sed -i 's/^#user_allow_other/user_allow_other/' /etc/fuse.conf

# Add user to fuse group
sudo groupadd fuse
sudo usermod -aG fuse $USER

Usage

Managing Spoke Tunnels

• Docker on spoke should handle autostart of spoke tunnel
• Syncthing can be combined in this image
• Rename syncthing image and host names per-device in the compose file.

# Build autossh container
./hubspoke-helper.sh spoke build

# Start/stop/restart tunnel
./hubspoke-helper.sh spoke start
./hubspoke-helper.sh spoke stop
./hubspoke-helper.sh spoke restart

# Check status and logs
./hubspoke-helper.sh spoke status
./hubspoke-helper.sh spoke logs

# Show manual autossh command
./hubspoke-helper.sh spoke show-cmd

Managing Hub Mounts

Crontab entry:

@reboot /home/armbian/tinyboard/hubspoke-helper.sh hub start-background

Deprecated: systemd

# Install systemd service (after manual file placement)
./hubspoke-helper.sh hub install

# Start/stop rclone mount
./hubspoke-helper.sh hub start
./hubspoke-helper.sh hub stop

# Check service status
./hubspoke-helper.sh hub status

# Manual mount/unmount for testing
./hubspoke-helper.sh hub mount
./hubspoke-helper.sh hub unmount

Configuration Variables

Environment variables can override defaults:

• TUNNEL_DIR: Directory containing spoke Docker files (default: ~/tinyboard/spoke)
• COMPOSE_FILE: Docker compose file path (default: $TUNNEL_DIR/compose.yaml)
• RCLONE_REMOTE: Rclone remote name (default: brie-remote)
• MOUNT_POINT: Mount point on hub (default: ~/mnt/hub)

Security Notes

1. SSH Keys: Always use strong key pairs and protect private keys
2. Configuration Files: Use spoke/clean_sensitive.sh to remove WiFi credentials before committing
3. Firewall: Ensure proper firewall rules on hub (port 11111 for reverse tunnels)
4. User Permissions: Run services with minimal required privileges

Troubleshooting

Spoke Tunnel Issues

• Check Docker container logs: ./hubspoke-helper.sh spoke logs
• Verify SSH key permissions: chmod 600 ~/.ssh/oilykey2026
• Test SSH connection manually: ssh -p 11111 armbian@localhost

Hub Mount Issues

• Check service status: ./hubspoke-helper.sh hub status
• Test rclone manually: rclone lsd brie-sftp:
• Verify fuse configuration: ls -la /etc/fuse.conf
• Check user groups: groups $USER

Network Issues

• Ensure spokes can reach hub on SSH port (22)
• Verify reverse tunnel port (11111) is not blocked by firewall
• Check DNS resolution on spokes for hub hostname

Maintenance

Updating Configuration

1. Update spoke/compose.yaml for new spoke hostnames
2. Update hub/rclone.conf for new spoke connections
3. Update spoke/autohostname.sh for new MAC addresses

Adding New Spokes

1. Follow Spoke Setup steps for new device
2. Add MAC address to spoke/autohostname.sh
3. Update hub's SSH authorized_keys with new spoke public key
4. Add new rclone remote configuration if needed

License

This project is for personal use. Adapt as needed for your environment.