Update provisioning documentation and scripts for improved Proxmox deployment</message>
<message>Add a new step-by-step guide for deploying the CM4 eMMC provisioning service on a new Proxmox instance, enhancing clarity for users. Update existing documentation to reflect changes in network configuration options, including the introduction of LAN subnet settings for DHCP and TFTP. Modify cloud-init scripts to ensure proper management of DNS settings and improve the handling of network interfaces. Additionally, enhance the toggle script for network boot to dynamically read the LAN gateway from configuration files, streamlining the setup process and improving user experience.
This commit is contained in:
nearxos
152
emmc-provisioning/docs/DEPLOY-NEW-PROXMOX.md
Normal file
152
emmc-provisioning/docs/DEPLOY-NEW-PROXMOX.md
Normal file
@@ -0,0 +1,152 @@
|
||||
# Deploy CM4 eMMC Provisioning to a New Proxmox Instance
|
||||
|
||||
Step-by-step guide to deploy the provisioning service (host + LXC) on a **new** Proxmox server. For redeploy/update and troubleshooting, see [PROXMOX-LXC-DEPLOYMENT.md](PROXMOX-LXC-DEPLOYMENT.md).
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites (before running the deploy script)
|
||||
|
||||
| Requirement | Details |
|
||||
|-------------|---------|
|
||||
| **Proxmox host** | A Proxmox VE node (new or existing) where you want the service. |
|
||||
| **SSH as root** | You must be able to run `ssh root@YOUR_PROXMOX_HOST` with **key-based auth** (no password prompt). |
|
||||
| **Proxmox storage** | At least one active storage (e.g. `local` or `local-lvm`). Check on the host: `pvesm status`. |
|
||||
| **Host internet** (recommended) | Needed so the deploy script can download the Debian 12 LXC template (if missing), and install **usbboot** and **PiShrink** on the host. Without internet, deploy still runs but you must install usbboot and PiShrink manually later. |
|
||||
|
||||
**Optional (set before deploy):**
|
||||
|
||||
- `DEPLOY_ROOTFS_STORAGE=local-lvm` — Skip interactive storage choice when creating the LXC.
|
||||
- `DEPLOY_LXC_ROOT_PASSWORD=yourpassword` — Set LXC root password and enable SSH.
|
||||
- `DEPLOY_LXC_SSH_KEY=/path/to/pub` — Copy this key into the LXC (default: `~/.ssh/id_ed25519.pub` or `id_rsa.pub`).
|
||||
- `CM4_BACKUPS_HOST_PATH=/mnt/storage/cm4-backups` — Store backups on this host path (create the directory on the host if needed).
|
||||
- **Network (WAN/LAN):**
|
||||
`DEPLOY_LXC_WAN_BRIDGE=vmbr0` (default), `DEPLOY_LXC_WAN_IP=dhcp` (default),
|
||||
`DEPLOY_LXC_LAN_BRIDGE=vmbr1`, `DEPLOY_LXC_LAN_SUBNET=10.20.50.1/24` — To add eth1 as provisioning LAN with a custom subnet.
|
||||
|
||||
---
|
||||
|
||||
## Step 1: Run the deploy script
|
||||
|
||||
From your **workstation** (where the repo is cloned), run:
|
||||
|
||||
```bash
|
||||
cd /path/to/reTerminal\ DM4
|
||||
|
||||
./emmc-provisioning/scripts/deploy-to-proxmox.sh root@YOUR_PROXMOX_HOST
|
||||
```
|
||||
|
||||
Replace `YOUR_PROXMOX_HOST` with the Proxmox hostname or IP (e.g. `10.20.30.40`).
|
||||
|
||||
**Example with options:**
|
||||
|
||||
```bash
|
||||
DEPLOY_ROOTFS_STORAGE=local-lvm \
|
||||
DEPLOY_LXC_ROOT_PASSWORD='YourSecurePassword' \
|
||||
DEPLOY_LXC_LAN_BRIDGE=vmbr1 \
|
||||
DEPLOY_LXC_LAN_SUBNET=10.20.50.1/24 \
|
||||
./emmc-provisioning/scripts/deploy-to-proxmox.sh root@10.20.30.40
|
||||
```
|
||||
|
||||
- On **first run**, the script will ask you to choose LXC rootfs storage (unless `DEPLOY_ROOTFS_STORAGE` is set). It then creates the LXC, installs host scripts, udev, systemd units, and the dashboard in the LXC.
|
||||
- The script prints the **LXC IP** at the end. Note it for the next steps (or get it with:
|
||||
`ssh root@YOUR_PROXMOX_HOST "pct exec \$(pct list -no-header -output vmid,name | awk '\''\$2==\"cm4-provisioning\"{print \$1}'\'') -- hostname -I"`).
|
||||
|
||||
---
|
||||
|
||||
## Step 2: Install usbboot on the host (if host had no internet during deploy)
|
||||
|
||||
USB flash/backup needs **rpiboot** on the Proxmox **host**. If the deploy log said usbboot install failed or was skipped:
|
||||
|
||||
**From your workstation:**
|
||||
|
||||
```bash
|
||||
scp emmc-provisioning/scripts/install-usbboot-on-host.sh root@YOUR_PROXMOX_HOST:/tmp/
|
||||
ssh root@YOUR_PROXMOX_HOST "bash /tmp/install-usbboot-on-host.sh"
|
||||
```
|
||||
|
||||
**Or on the Proxmox host** (if `/tmp/emmc-provisioning-deploy` is still there):
|
||||
|
||||
```bash
|
||||
ssh root@YOUR_PROXMOX_HOST
|
||||
bash /tmp/emmc-provisioning-deploy/scripts/install-usbboot-on-host.sh
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 3: Add a golden image (required for Deploy)
|
||||
|
||||
To **write** an image to a device (Deploy), the host must have a **golden image** at `/var/lib/cm4-provisioning/golden.img`. Backup (read from device) works without it.
|
||||
|
||||
**Option A — From the dashboard**
|
||||
|
||||
1. Open **http://<LXC-IP>:5000** (use the LXC IP from the deploy output).
|
||||
2. Build a cloud-init image or upload/set an existing backup as golden (see dashboard Admin).
|
||||
|
||||
**Option B — Copy an image from your machine**
|
||||
|
||||
```bash
|
||||
scp /path/to/your-golden.img root@YOUR_PROXMOX_HOST:/var/lib/cm4-provisioning/golden.img
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 4: (Optional) SSH into the LXC
|
||||
|
||||
If you set `DEPLOY_LXC_ROOT_PASSWORD` or had a default SSH key, you can already run:
|
||||
|
||||
```bash
|
||||
ssh root@<LXC-IP>
|
||||
```
|
||||
|
||||
Otherwise, enable root SSH and add your key:
|
||||
|
||||
```bash
|
||||
./emmc-provisioning/scripts/setup-lxc-ssh.sh root@YOUR_PROXMOX_HOST
|
||||
# Or with password: ROOT_PASSWORD='YourPassword' ./emmc-provisioning/scripts/setup-lxc-ssh.sh root@YOUR_PROXMOX_HOST ~/.ssh/id_ed25519.pub
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 5: (Optional) Network boot (DHCP + TFTP on eth1)
|
||||
|
||||
Only if you deployed with **`DEPLOY_LXC_LAN_BRIDGE`** (and optionally `DEPLOY_LXC_LAN_SUBNET`) and want to offer network boot to devices on that LAN:
|
||||
|
||||
```bash
|
||||
./emmc-provisioning/scripts/setup-network-boot-on-lxc.sh root@<LXC-IP>
|
||||
```
|
||||
|
||||
See [NETWORK-BOOT-LXC.md](NETWORK-BOOT-LXC.md) for details.
|
||||
|
||||
---
|
||||
|
||||
## Step 6: (Optional) Install PiShrink on the host
|
||||
|
||||
If the deploy log said PiShrink install failed (e.g. no internet), and you want **Shrink/Compress** in the dashboard to work:
|
||||
|
||||
```bash
|
||||
ssh root@YOUR_PROXMOX_HOST "bash /tmp/emmc-provisioning-deploy/scripts/install-pishrink-on-host.sh"
|
||||
```
|
||||
|
||||
Or from your machine (stream the script): use the same pattern as in [PROXMOX-LXC-DEPLOYMENT.md](PROXMOX-LXC-DEPLOYMENT.md) for `install-pishrink-on-host.sh`.
|
||||
|
||||
---
|
||||
|
||||
## Summary checklist
|
||||
|
||||
| Step | Action | Required? |
|
||||
|------|--------|------------|
|
||||
| 1 | Run `deploy-to-proxmox.sh root@YOUR_PROXMOX_HOST` | **Yes** |
|
||||
| 2 | Install usbboot on host (if deploy couldn’t) | For USB flash/backup |
|
||||
| 3 | Add `golden.img` for Deploy | For Deploy only |
|
||||
| 4 | SSH to LXC (or use setup-lxc-ssh.sh) | Optional |
|
||||
| 5 | Run setup-network-boot-on-lxc.sh (if using eth1 LAN) | Optional |
|
||||
| 6 | Install PiShrink on host (if deploy couldn’t) | For Shrink/Compress |
|
||||
|
||||
**After deployment:**
|
||||
|
||||
- **Dashboard:** http://<LXC-IP>:5000
|
||||
- **Golden image path (host and LXC):** `/var/lib/cm4-provisioning/golden.img`
|
||||
- **Disable auto-flash:** `ssh root@YOUR_PROXMOX_HOST "rm /etc/cm4-provisioning/enabled"`
|
||||
- **Enable again:** `ssh root@YOUR_PROXMOX_HOST "touch /etc/cm4-provisioning/enabled"`
|
||||
|
||||
Full reference: [PROXMOX-LXC-DEPLOYMENT.md](PROXMOX-LXC-DEPLOYMENT.md).
|
||||
@@ -1,4 +1,4 @@
|
||||
# How to edit cloud-init files on the device before capturing the image
|
||||
# How to edit cloud-init files on the device or on an image file
|
||||
|
||||
The cloud-init **NoCloud** files live on the **boot partition**. On the running device they are at:
|
||||
|
||||
@@ -77,6 +77,34 @@ They are owned by **root** and need **sudo** to edit.
|
||||
|
||||
---
|
||||
|
||||
## Method 3: Edit on an image file (.img or .img.xz)
|
||||
|
||||
To edit cloud-init **inside a disk image** (e.g. `gnss-bootstrap-20260223-215010.img.xz`) without booting the device:
|
||||
|
||||
1. **Run the helper script** (requires `sudo` for loop device and mount):
|
||||
|
||||
```bash
|
||||
cd /path/to/reTerminal-DM4
|
||||
./emmc-provisioning/scripts/edit-cloudinit-on-image.sh gnss-bootstrap-20260223-215010.img.xz
|
||||
```
|
||||
|
||||
2. The script will:
|
||||
- Decompress the `.img.xz` (if needed; allow ~3GB free space and a minute or two)
|
||||
- Attach the image with `losetup` and mount the **boot** (FAT32) partition
|
||||
- Open your `$EDITOR` (or `nano`) on `user-data`, `meta-data`, and `network-config`
|
||||
- After you save and exit, unmount and recompress, **overwriting** the original `.img.xz`
|
||||
|
||||
3. **Back up the image** before running if you want to keep the original:
|
||||
```bash
|
||||
cp gnss-bootstrap-20260223-215010.img.xz gnss-bootstrap-20260223-215010.img.xz.bak
|
||||
```
|
||||
|
||||
4. **Options:**
|
||||
- `--no-recompress` — Leave the image decompressed after editing (do not overwrite the `.img.xz`).
|
||||
- `--replace-with-repo` — Copy `user-data`, `meta-data`, and `network-config` from `emmc-provisioning/cloud-init/` into the image before opening the editor (useful to start from repo templates).
|
||||
|
||||
---
|
||||
|
||||
## What to edit (typical)
|
||||
|
||||
- **meta-data**
|
||||
|
||||
@@ -48,7 +48,13 @@ The script will:
|
||||
|
||||
## Proxmox: adding eth1 to the LXC
|
||||
|
||||
If you create the container by hand or want a second interface:
|
||||
Use the deploy script with **`DEPLOY_LXC_LAN_BRIDGE`** and **`DEPLOY_LXC_LAN_SUBNET`** so the LXC is created with eth1 (LAN) from the start:
|
||||
|
||||
```bash
|
||||
DEPLOY_LXC_LAN_BRIDGE=vmbr1 DEPLOY_LXC_LAN_SUBNET=10.20.50.1/24 ./emmc-provisioning/scripts/deploy-to-proxmox.sh root@YOUR_PROXMOX_HOST
|
||||
```
|
||||
|
||||
Or add a second interface to an existing container by hand:
|
||||
|
||||
1. On the **Proxmox host**, add a second network device to the container, e.g.:
|
||||
```bash
|
||||
@@ -65,6 +71,22 @@ If you create the container by hand or want a second interface:
|
||||
|
||||
Your current LXC already has eth0 (10.130.60.141) and eth1 (10.20.50.1); the setup script only adds DHCP, TFTP, and NAT.
|
||||
|
||||
### Changing the LAN subnet
|
||||
|
||||
When you deploy with **`DEPLOY_LXC_LAN_SUBNET`** (e.g. `10.100.1.1/24`), the deploy script writes **`/opt/cm4-provisioning/lan-subnet.conf`** inside the LXC with `LAN_GW`, `LAN_CIDR`, and the DHCP range. All LXC services use this file:
|
||||
|
||||
- **dnsmasq** (DHCP range and, via the toggle script, TFTP next-server)
|
||||
- **nftables/iptables** (NAT source subnet)
|
||||
- **toggle-network-boot-dhcp.sh** (option 66/67 next-server)
|
||||
|
||||
So changing `DEPLOY_LXC_LAN_SUBNET` and **re-running the deploy script** updates `lan-subnet.conf`. To apply the new subnet to dnsmasq and NAT, **re-run the setup script** after redeploying:
|
||||
|
||||
```bash
|
||||
./emmc-provisioning/scripts/setup-network-boot-on-lxc.sh root@<LXC-IP>
|
||||
```
|
||||
|
||||
Then run **toggle enable** again if you use network boot: `ssh root@<LXC-IP> /opt/cm4-provisioning/toggle-network-boot-dhcp.sh enable`
|
||||
|
||||
## After setup: reTerminal network boot
|
||||
|
||||
1. Set the reTerminal **boot order** to try eMMC first, then network (e.g. `BOOT_ORDER=0xf21`): use the dashboard **Update EEPROM** when the device is connected via USB boot, or set manually (usbboot recovery / `rpi-eeprom-config` on device). Not set by first-boot.
|
||||
|
||||
@@ -2,6 +2,8 @@
|
||||
|
||||
The auto-flash **runs on the Proxmox host** (where the USB device appears). The **LXC** holds the dashboard and shares the **golden image** directory with the host.
|
||||
|
||||
**New deployment:** For a clear step-by-step guide to deploy on a **new** Proxmox instance, see **[DEPLOY-NEW-PROXMOX.md](DEPLOY-NEW-PROXMOX.md)**.
|
||||
|
||||
## One-command deploy
|
||||
|
||||
From your repo, a single run deploys **all** host and LXC files (scripts, systemd units, udev, dashboard):
|
||||
@@ -12,6 +14,8 @@ From your repo, a single run deploys **all** host and LXC files (scripts, system
|
||||
|
||||
Optional env: `CM4_BACKUPS_HOST_PATH=/path`, `DEPLOY_ROOTFS_STORAGE=local-lvm`, `DEPLOY_LXC_ROOT_PASSWORD=secret` (set root password in LXC and enable SSH), `DEPLOY_LXC_SSH_KEY=/path/to/pub` (default: `~/.ssh/id_ed25519.pub` or `id_rsa.pub` — copied to LXC root so you can `ssh root@<LXC-IP>`).
|
||||
|
||||
**Network (WAN / LAN):** `DEPLOY_LXC_WAN_BRIDGE=vmbr0` (default), `DEPLOY_LXC_WAN_IP=dhcp` (default or e.g. `192.168.1.10/24`), `DEPLOY_LXC_LAN_BRIDGE=vmbr1` (if set, add eth1 as LAN), `DEPLOY_LXC_LAN_SUBNET=10.20.50.1/24` (LXC IP on LAN; default `10.20.50.1/24` when LAN bridge is set). Example: `DEPLOY_LXC_WAN_BRIDGE=vmbr0 DEPLOY_LXC_LAN_BRIDGE=vmbr1 DEPLOY_LXC_LAN_SUBNET=10.20.50.1/24 ./scripts/deploy-to-proxmox.sh root@host`.
|
||||
|
||||
The script **finds the container by hostname `cm4-provisioning`** (any existing ID). If none exists, it **creates a new LXC with the next available ID**. So you can redeploy repeatedly without assuming a fixed ID like 201.
|
||||
|
||||
## What is deployed
|
||||
|
||||
Reference in New Issue
Block a user