update readme

2026-04-13 13:08:32 -07:00
parent 299f6c5355
commit 0c182f7dcb
3 changed files with 209 additions and 18 deletions
--- a/README.md
+++ b/README.md
@@ -1,24 +1,204 @@
-### Initial SD setup
-1. Write armbian minimal to SD
-2. Copy `not_logged_in_yet` over to allow wifi connection.
-3. SSH in as root with password "1234", NOT the password in `not_logged_in_yet`
-4. After first login, `not_logged_in_yet` will be processed for root and armbian user creds.
-5. Future: `armbian-config` to switch to stable channel updates? NOPE dpkg errors 2026-04
-6. Git clone tinyboard repo as root.
-7. Run aptprimary and autohostname scripts.
-8. Reboot. Test as armbian user with configured passwords.
-9. Set up ssh keys.
+# TinyBoard Hub-Spoke File Sharing System

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

-### VPS Setup:
+## Architecture Overview

-`apt install rclone fuse
-adduser armbian
-groupadd fuse
-usermod -aG fuse armbian
+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
-`

-* setup ssh keys
+# 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.