From 0c182f7dcb531652c16f2c2ed444c89f0aa7d785 Mon Sep 17 00:00:00 2001 From: finn Date: Mon, 13 Apr 2026 13:08:32 -0700 Subject: [PATCH] update readme --- README.md | 214 ++++++++++++++++++++++++++++++++--- hub/rclone.conf | 9 ++ spoke/autossh-tunnel.service | 4 +- 3 files changed, 209 insertions(+), 18 deletions(-) create mode 100644 hub/rclone.conf diff --git a/README.md b/README.md index 7d9d31d..19881d5 100644 --- 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 ` +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@` +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. diff --git a/hub/rclone.conf b/hub/rclone.conf new file mode 100644 index 0000000..0c2e876 --- /dev/null +++ b/hub/rclone.conf @@ -0,0 +1,9 @@ +[brie-sftp] +type = sftp +host = localhost +port = 11111 +key_file = /home/armbian/.ssh/armbian-brie-202604 +shell_type = unix +md5sum_command = md5sum +sha1sum_command = sha1sum + diff --git a/spoke/autossh-tunnel.service b/spoke/autossh-tunnel.service index 796ee08..1b2bfd2 100644 --- a/spoke/autossh-tunnel.service +++ b/spoke/autossh-tunnel.service @@ -1,3 +1,5 @@ +# For now, deprecated in favor of docker tunnel + [Unit] Description=AutoSSH tunnel from spoke to hub After=network.target @@ -10,4 +12,4 @@ RestartSec=10 User=armbian [Install] -WantedBy=multi-user.target \ No newline at end of file +WantedBy=multi-user.target