rpi-img-builder

📋 Tabla de contenidos

🗺 Matrices de soporte

Sistema operativo ×ばつ Release

Arquitectura ×ばつ Hardware

Variantes

📦 Imágenes precompiladas

🔧 Dependencias

binfmt-support dosfstools rsync wget
lsof git parted dirmngr
e2fsprogs systemd-container debootstrap xz-utils
kmod udev dbus gnupg
gnupg-utils debian-archive-keyring
qemu-user-static (o qemu-user-binfmt en Debian 13+ / Ubuntu 26.04+)

⚡ Configuración rápida

# Imagen por defecto: debian bookworm lite arm64
sudo ./rpi-img-builder.sh
# RaspiOS bookworm arm64 comprimido en xz
sudo OS="raspios" RELEASE="bookworm" COMPRESS="xz" ./rpi-img-builder.sh
# Debian trixie arm64 con paquetes extra
sudo RELEASE="trixie" ADDPKG="nano htop tmux" ./rpi-img-builder.sh

🎛 Variables de entorno

Sistema

sudo OS="raspios" RELEASE="bookworm" VARIANT="lite" ARCHITECTURE="arm64" ./rpi-img-builder.sh

Almacenamiento

# Imagen con sistema de archivos f2fs y 512 MiB libres en root
sudo FSTYPE="f2fs" FREE_SPACE="512" ./rpi-img-builder.sh

Red

# Configuración de red estática
sudo IPV4="192.168.1.50" NETMASK="255.255.255.0" ROUTER="192.168.1.1" DNS="1.1.1.1" ./rpi-img-builder.sh

WiFi

sudo WPA_ESSID="MiRed" WPA_PASSWORD="mipassword" WPA_COUNTRY="ES" ./rpi-img-builder.sh

Sistema y localización

sudo ROOT_PASSWORD="s3cur3!" TIMEZONE="Europe/London" LOCALES="en_GB.UTF-8" ./rpi-img-builder.sh

Imagen de salida

sudo COMPRESS="xz" ADDPKG="nano htop curl jq" ./rpi-img-builder.sh

🔬 Opciones avanzadas (SysAdmin)

Manifiesto de paquetes

sudo MANIFEST="true" ./rpi-img-builder.sh
# Genera: debian-bookworm-lite-arm64.img.manifest

Proxy y caché APT

# Deshabilitar proxy aunque apt-cacher-ng esté activo
sudo PROXY_URL="" ./rpi-img-builder.sh
# Usar proxy externo
sudo PROXY_URL="http://proxy.lan:3142" ./rpi-img-builder.sh

Servidor de claves GPG personalizado

# Sobreescribir las URLs de descarga de claves
export PIOS_KEY_URL="http://mirror.interno/raspberrypi.gpg.key"
export RASP_KEY_URL="http://mirror.interno/raspbian.public.key"
sudo ./rpi-img-builder.sh

Modo debug

sudo ./rpi-img-builder.sh --debug
# Genera: rpi-img-builder.log en el directorio actual

Construir solo una arquitectura específica en un host arm64

update-binfmts --enable qemu-arm
sudo ARCHITECTURE="armhf" ./rpi-img-builder.sh

📄 config.txt — Configuración persistente

# config.txt — ejemplo sysadmin completo
OS="raspios"
RELEASE="bookworm"
ARCHITECTURE="arm64"
VARIANT="lite"
FSTYPE="ext4"
BOOT_MB="256"
FREE_SPACE="512"
HOST_NAME="rpi-prod-01"
ROOT_PASSWORD="c4mb14m3!"
COMPRESS="xz"
TIMEZONE="Europe/Madrid"
LOCALES="es_ES.UTF-8"
ADDPKG="nano htop tmux rsync curl jq sudo"
WPA_ESSID="LabNet"
WPA_PASSWORD="labpassword"
WPA_COUNTRY="ES"
IPV4="10.0.0.50"
NETMASK="255.255.255.0"
ROUTER="10.0.0.1"
DNS="10.0.0.1"
MANIFEST="true"

🌐 Proxy y caché APT

# Instalar apt-cacher-ng en el host
sudo apt-get install apt-cacher-ng
sudo systemctl enable --now apt-cacher-ng
# El script lo detecta automáticamente en el puerto 3142
sudo ./rpi-img-builder.sh

🚀 Ejemplos de uso

Imagen mínima por defecto

sudo ./rpi-img-builder.sh

RaspiOS bookworm arm64 comprimido

sudo OS="raspios" RELEASE="bookworm" COMPRESS="xz" ./rpi-img-builder.sh

Debian trixie armhf con IP estática y paquetes extra

sudo RELEASE="trixie" \
 ARCHITECTURE="armhf" \
 HOST_NAME="rpi-trixie" \
 IPV4="192.168.10.200" \
 NETMASK="255.255.255.0" \
 ROUTER="192.168.10.1" \
 DNS="1.1.1.1" \
 ADDPKG="nano htop tmux" \
 COMPRESS="xz" \
 ./rpi-img-builder.sh

Build completo desde config.txt (recomendado para producción)

wget https://github.com/FrangaL/rpi-img-builder/raw/master/rpi-img-builder.sh
chmod +x rpi-img-builder.sh
cat > config.txt << 'EOF'
OS="debian"
RELEASE="bookworm"
ARCHITECTURE="arm64"
VARIANT="lite"
HOST_NAME="rpi4-server"
ROOT_PASSWORD="s3cur3p4ss"
COMPRESS="xz"
TIMEZONE="Europe/Madrid"
LOCALES="es_ES.UTF-8"
ADDPKG="nano htop tmux curl jq"
MANIFEST="true"
EOF
sudo ./rpi-img-builder.sh

🐳 Contenedor Docker

wget https://git.io/rpi-images-builder.yml
docker-compose -f rpi-images-builder.yml --compatibility up -d
docker exec -it rpi-images git pull
# Build con variables de entorno
docker exec -it rpi-images bash -c \
 "OS=raspios RELEASE=bookworm COMPRESS=xz ./rpi-img-builder.sh"
# Copiar imagen generada al host
docker cp rpi-images:/images/raspios-bookworm-lite-arm64.img.xz .

💾 Flashear la imagen

# Verificar el dispositivo correcto
lsblk -o NAME,SIZE,MODEL,TRAN | grep -E "sd|mmcblk"

# Imagen comprimida en xz (más rápido con tuberías)
xzcat raspios-bookworm-lite-arm64.img.xz | \
 sudo dd of=/dev/sdX bs=64k oflag=dsync status=progress
# Imagen comprimida en gz
gzip -dc debian-bookworm-lite-arm64.img.gz | \
 sudo dd of=/dev/sdX bs=64k oflag=dsync status=progress
# Imagen sin comprimir
sudo dd if=debian-bookworm-lite-arm64.img \
 of=/dev/sdX bs=64k oflag=dsync status=progress
# Alternativa con pv para barra de progreso más legible
xzcat raspios-bookworm-lite-arm64.img.xz | pv | sudo dd of=/dev/sdX bs=64k oflag=dsync

🐛 Debugging

# Ejecución con log completo
sudo ./rpi-img-builder.sh --debug
# El log se guarda en rpi-img-builder.log
tail -f rpi-img-builder.log

./{OS}_{RELEASE}_{VARIANT}_{ARCHITECTURE}/

sudo rm -rf ./debian_bookworm_lite_arm64/