# 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-mount@.service   # Systemd user service template
│   └── rclone.conf             # Rclone SFTP configuration
├── spoke/
│   ├── compose.yaml            # Docker Compose for autossh tunnel
│   ├── Dockerfile              # autossh container image
│   ├── autossh-tunnel.service  # Legacy systemd service (deprecated)
│   ├── 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

### 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 (contains WiFi credentials)
3. Boot device, SSH in as root with password "1234"
4. After first login, `armb-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
```bash
# 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

### Systemd Service Setup
1. Create user systemd directory: `mkdir -p ~/.config/systemd/user`
2. Copy `hub/rclone-mount@.service` to `~/.config/systemd/user/`
3. Enable lingering for user services: `sudo loginctl enable-linger $USER`
4. Reload systemd: `systemctl --user daemon-reload`

### FUSE Configuration
```bash
# 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
```bash
# 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
```bash
# 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/brie`)

## 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.