Skip to content

Instantly share code, notes, and snippets.

@arvati
Last active July 20, 2026 04:16
Show Gist options
  • Select an option

  • Save arvati/399510f14604fb4c660fda650be2a95c to your computer and use it in GitHub Desktop.

Select an option

Save arvati/399510f14604fb4c660fda650be2a95c to your computer and use it in GitHub Desktop.
Pendrive Prime

🚀 O Guia Definitivo: Construindo um Pendrive Híbrido Supremo

UEFI/Legacy + exFAT (Windows) + LUKS2 + Btrfs + Debian Trixie via Debootstrap

Este guia técnico demonstra como criar um pendrive avançado capaz de dar boot em máquinas UEFI modernas e máquinas Legacy (BIOS) antigas através de um esquema de particionamento híbrido. O sistema operacional será o Debian Trixie rodando direto de um subvolume Btrfs criptografado.

Para fins de segurança e desenvolvimento, faremos todo o processo em um arquivo de imagem virtual que pode ser testado diretamente no QEMU/KVM (Virt-Manager).


🏗️ Parte 1: Preparação do Ambiente e Disco Virtual

Execute os comandos no terminal do seu Debian atual para instalar as ferramentas necessárias e criar o cenário de testes.

# 0. Algumas variáveis de configuração
EXFAT_SIZE="+16G"

# 1. Instalar dependências necessárias no sistema hospedeiro
sudo apt update && sudo apt install gdisk exfatprogs syslinux-common syslinux extlinux grub-pc-bin \
qemu-system-x86 qemu-utils libvirt-daemon-system libvirt-clients virt-manager osinfo-db ovmf debootstrap -y

# 2. Configurar permissões para o Virt-Manager (lembre-se de deslogar/logar após isso)
sudo usermod -aG libvirt $USER
sudo usermod -aG kvm $USER
sudo systemctl enable --now libvirtd

# 3. Criar o arquivo de imagem de 30GB que simulará o pendrive
dd if=/dev/zero of=pendrive.img bs=1M count=30000


# 4. Associar o arquivo a um dispositivo de loop virtual

#sudo losetup -P /dev/loop0 pendrive.img
DISK_DEV=$(sudo losetup -f --show -P pendrive.img)

# Caso queira usar um pendrive físico
DISK_DEV="/dev/sda"
[[ "$DISK_DEV" =~ "nvme" || "$DISK_DEV" =~ "mmcblk" || "$DISK_DEV" =~ "loop" ]] && PART_PREFIX="p" || PART_PREFIX=""

P1="${DISK_DEV}${PART_PREFIX}1"
P2="${DISK_DEV}${PART_PREFIX}2"
P3="${DISK_DEV}${PART_PREFIX}3"
P4="${DISK_DEV}${PART_PREFIX}4"

🗺️ Parte 2: Arquitetura de Particionamento (GPT Híbrido)

O segredo da compatibilidade com o Windows é colocar a partição de dados em exFAT na primeira posição física do disco. O segredo do boot duplo é o MBR Híbrido apontando apenas para a partição FAT32.

Usando somente comandos sem interação:

# 1. Limpa a tabela de partição existente
sudo sgdisk -Z "$DISK_DEV"

# 2. Configura o alinhamento e cria as partições em sequência
# Partição 1: Começa estritamente no setor 65536, deixando 32MB livres no início.
sudo sgdisk -a 2048 -n 1:65536:"$EXFAT_SIZE" -t 1:0700 -c 1:"DADOS" "$DISK_DEV"

# Partição 2: BIOS Boot (Note o tipo correto ef02 para GRUB em modo Legacy/BIOS)
sudo sgdisk -n 2:0:+2M           -t 2:ef02 -c 2:"BIOS_BOOT" "$DISK_DEV"

# Partição 3: EFI Boot (Tipo ef00 para UEFI)
sudo sgdisk -n 3:0:+500M         -t 3:ef00 -c 3:"BOOT_USB" "$DISK_DEV"

# Partição 4: Debian Root (Ocupa o restante do disco)
sudo sgdisk -n 4:0:0             -t 4:8300 -c 4:"LINUX" "$DISK_DEV"

sudo sgdisk -A 1:clear:63 "$DISK_DEV"

# 3. Cria o MBR Híbrido apontando para a partição 3 (geralmente usado para compatibilidade com Mac/antigos)
# Adiciona a partição 1 (exFAT) e a partição 3 (FAT32) no MBR Híbrido
sudo sgdisk -h 1:3 "$DISK_DEV"
echo -e "3\ny" | sudo sgdisk -h 1:3 "$DISK_DEV"

Execute o particionador interativo:

sudo gdisk /dev/loop0

Siga a sequência de comandos dentro do gdisk:

  1. o ➔ Confirme (Y) para criar uma nova tabela GPT limpa.
  2. n ➔ Partição 1 (exFAT - Dados Comuns do Usuário)
  • Número: 1 | Primeiro setor: Enter | Último setor: +20G | Código: 0700
  1. n ➔ Partição 2 (BIOS Boot - Necessária para o GRUB Legacy em GPT)
  • Número: 2 | Primeiro setor: Enter | Último setor: +2M | Código: ef02
  1. n ➔ Partição 3 (ESP / Boot FAT32 - Arquivos do GRUB/Syslinux)
  • Número: 3 | Primeiro setor: Enter | Último setor: +500M | Código: ef00
  1. n ➔ Partição 4 (Debian Root - Criptografada)
  • Número: 4 | Primeiro setor: Enter | Último setor: Enter (Restante) | Código: 8300

Criando o Hybrid MBR (A Ponte Legacy):

  1. r ➔ Entra no menu de recuperação do gdisk.
  2. h ➔ Ativa a criação do Hybrid MBR.
  3. Digite 1 3 ➔ Adiciona apenas a partição FAT32 de boot e a partição extFAT ao MBR.
  4. y ➔ Place EFI GPT partition first? Sim.
  5. 07 ➔ Código MBR para a partição 1
  6. 0c ➔ Código MBR para a partição 3 (FAT32 LBA).
  7. y ➔ Set the bootable flag? Sim (Torna a partição ativa para a BIOS antiga).
  8. w ➔ Grava as alterações no disco e confirma (Y).

💾 Parte 3: Formatação e Instalação dos Bootloaders

# 1. Formatar a área visível do Windows e a área de boot
sudo mkfs.exfat -n "DADOS" "$P1"
sudo mkfs.vfat -F 32 -n "BOOT_USB" "$P3"

# 2. Montar a partição de boot para instalar os gerenciadores
sudo mkdir -p /mnt/usb
sudo mount "$P3" /mnt/usb

# 3. INSTALAÇÃO UEFI (GRUB2 Nativo)
sudo grub-install --target=x86_64-efi --efi-directory=/mnt/usb --boot-directory=/mnt/usb/boot --removable

# 4. INSTALAÇÃO LEGACY (Gerando o binário g2ldr para o Syslinux chamar)

sudo mkdir -p /mnt/usb/boot/grub/i386-pc
sudo cp /usr/lib/grub/i386-pc/*.mod /mnt/usb/boot/grub/i386-pc/
sudo cp /usr/lib/grub/i386-pc/*.lst /mnt/usb/boot/grub/i386-pc/

sudo grub-mkimage -O i386-pc -o /mnt/usb/boot/grub/core.img -p '(hd0,gpt3)/boot/grub' \
biosdisk part_msdos part_gpt fat exfat ext2 btrfs \
crypto cryptodisk luks2 gcry_rijndael gcry_sha256 gzio test normal

sudo cat /usr/lib/grub/i386-pc/lnxboot.img /mnt/usb/boot/grub/core.img | sudo tee /mnt/usb/boot/grub/g2ldr > /dev/null

# 5. INSTALAÇÃO DO SYSLINUX NO MBR HÍBRIDO
sudo dd bs=440 count=1 conv=notrunc if=/usr/lib/syslinux/mbr/mbr.bin of="$DISK_DEV"

sudo mkdir -p /mnt/usb/boot/syslinux

# 5.1 Instalação com syslinux - válido para discos fisicos
sudo syslinux --install "$P3"

# 5.2 Instalação com extlinux - válido para arquivo pendrive.img
sudo extlinux --install /mnt/usb/boot/syslinux
sudo ln -sf extlinux.conf /mnt/usb/boot/syslinux/syslinux.cfg

# 6. Configurar estrutura do Syslinux
sudo cp /usr/lib/syslinux/modules/bios/ldlinux.c32 /mnt/usb/boot/syslinux/

sudo tee /mnt/usb/boot/syslinux/syslinux.cfg << 'EOF'
DEFAULT grub2
LABEL grub2
    MENU LABEL Carregar GRUB2 Hibrido via Syslinux
    KERNEL /boot/grub/g2ldr
EOF

🐧 Parte 4: Criação do LUKS2, Btrfs e Instalação do Debian Trixie

Usaremos o debootstrap para fazer uma instalação cirúrgica e limpa do Debian Testing (Trixie) direto no subvolume light.

# 1. Criar e abrir o contêiner criptografado LUKS2 na Partição 4
sudo cryptsetup luksFormat --type luks2 --pbkdf pbkdf2 "$P4"
sudo cryptsetup open "$P4" luks

# 2. Formatar em Btrfs e estruturar os subvolumes (Raiz em 'light')
sudo mkfs.btrfs -L "ROOT" /dev/mapper/luks
sudo mkdir -p /mnt/btrfs
sudo mount /dev/mapper/luks /mnt/btrfs
sudo mkdir /mnt/btrfs/snapshots

sudo btrfs subvolume create /mnt/btrfs/light
sudo umount /mnt/btrfs

# 3. Montar o subvolume 'light' para a instalação
sudo mkdir -p /mnt/debian
sudo mount -o subvol=light /dev/mapper/luks /mnt/debian

# 4. Rodar o Debootstrap para baixar o Debian Trixie básico
sudo debootstrap --arch amd64 trixie /mnt/debian http://deb.debian.org/debian/

# 5. Preparar o ambiente Chroot
sudo mount --bind /dev /mnt/debian/dev
sudo mount --bind /proc /mnt/debian/proc
sudo mount --bind /sys /mnt/debian/sys
sudo mount --bind /dev/pts /mnt/debian/dev/pts

for i in /dev /dev/pts /proc /sys /run; do sudo mount --bind $i /mnt/debian$i; done

# 6. Entrar no novo sistema para configurações internas
sudo chroot /mnt/debian /bin/bash

⚠️ COMANDOS EXECUTADOS DENTRO DO AMBIENTE CHROOT (DEBIAN TRIXIE VIRTUAL):

# Configurar repositórios do Trixie
cat << 'EOF' > /etc/apt/sources.list
deb http://deb.debian.org/debian/ trixie main contrib non-free non-free-firmware
deb http://deb.debian.org/debian/ trixie-updates main contrib non-free non-free-firmware
deb http://security.debian.org/debian-security trixie-security main contrib non-free non-free-firmware
EOF

# Atualizar e instalar o Kernel do Linux e ferramentas de criptografia
apt update
apt install linux-image-amd64 cryptsetup-initramfs btrfs-progs locales ntfs-3g exfat-fuse dosfstools btrfs-progs f2fs-tools nfs-common cifs-utils -y
dpkg-reconfigure locales


# Definir a senha do usuário Root do sistema
echo "Defina a senha do ROOT:"
passwd root

# Configurar fstab básico
cat << 'EOF' > /etc/fstab
/dev/mapper/luks  /  btrfs  defaults,subvol=light  0  1
EOF

UUID_LUKS=$(blkid -s UUID -o value /dev/sda4)
echo "luks UUID=$UUID_LUKS none luks,initramfs" > /etc/crypttab

echo "GRUB_ENABLE_CRYPTODISK=y" >>/etc/default/grub

echo "CRYPTSETUP=y" >> /etc/cryptsetup-initramfs/conf-hook
echo "KEYFILE_PATTERN=\"/etc/luks-keys/*.key\"" >> /etc/cryptsetup-initramfs/conf-hook
echo UMASK=0077 >> /etc/initramfs-tools/initramfs.conf
update-initramfs -u -k all

# Sair do Chroot
exit

⚙️ Parte 5: Vinculando o GRUB2 ao Sistema Criptografado

Agora, extraímos o kernel gerado e configuramos o grub.cfg principal na partição FAT32.

# 1. Copiar os binários do Kernel para fora (Agiliza a leitura inicial do GRUB)
sudo mkdir -p /mnt/usb/boot/
sudo cp /mnt/debian/boot/vmlinuz-* /mnt/usb/boot/vmlinuz
sudo cp /mnt/debian/boot/initrd.img-* /mnt/usb/boot/initrd.img

# 2. Capturar o UUID real da partição LUKS2
UUID_LUKS=$(sudo blkid -s UUID -o value "$P4")

# 3. Escrever o grub.cfg definitivo
sudo tee /mnt/usb/boot/grub/grub.cfg << EOF
insmod luks2
insmod cryptodisk
insmod btrfs
insmod gzio
insmod part_gpt
insmod exfat

# Força o prompt de senha no estágio do GRUB
cryptomount -a

menuentry "Debian (rootfs)" {
    set root=(crypto0)
    linux (\$root)/rootfs/vmlinuz root=/dev/mapper/luks cryptdevice=UUID=$UUID_LUKS:luks rootflags=subvol=rootfs ro quiet splash
    initrd (\$root)/rootfs/initrd.img
}

menuentry "Debian (light)" {
    set root=(crypto0)
    linux (\$root)/light/vmlinuz root=/dev/mapper/luks cryptdevice=UUID=$UUID_LUKS:luks rootflags=subvol=light ro quiet splash
    initrd (\$root)/light/initrd.img
}

menuentry "Live ISO (/live.iso)" {
    set root=(hd0,gpt1)
    set isofile="/live.iso"
    
    # Faz o loopback da imagem ISO
    loopback loop (\$root)\$isofile

    linux (loop)/live/vmlinuz boot=live findiso=\$isofile components quiet splash
    initrd (loop)/live/initrd.img
}

menuentry "Reboot" { reboot }
menuentry "Poweroff" { halt }
if [ \${grub_platform} == "efi" ]; then
    menuentry "UEFI setup" { fwsetup  }
fi

EOF

🧹 Parte 6: Desmontagem e Limpeza Segura

# Desmontar binds do chroot
sudo umount /mnt/debian/dev/pts /mnt/debian/dev /mnt/debian/proc /mnt/debian/sys

# Desmontar diretórios de trabalho
sudo umount -l /mnt/debian
sudo umount /mnt/debian
sudo umount /mnt/usb

# Fechar criptografia e remover o disco virtual loop
sudo cryptsetup close luks
sudo losetup -d "$DISK_DEV"

echo "✅ PROCESSO CONCLUÍDO! O arquivo pendrive.img está pronto para testes."

🖥️ Parte 7: Como Testar no Virt-Manager (Interface Gráfica)

  1. Abra o Gerenciador de Máquinas Virtuais (virt-manager).
  2. Clique em Criar Nova VM ➔ Escolha "Importar imagem de disco existente".
  3. Selecione o caminho do seu arquivo pendrive.img.
  4. Avance definindo a memória RAM e CPU desejadas.
  5. Na última tela, marque "Editar configuração antes da instalação" e clique em Concluir.
  6. Na janela de opções da VM:
  • Para testar em Modo Legacy (BIOS): Em Firmware, garanta que esteja selecionado BIOS.
  • Para testar em Modo UEFI: Em Firmware, altere para UEFI x86_64 (OVMF).
  1. Vá em Opções de Inicialização, marque o disco rígido e coloque-o no topo da ordem de boot.
  2. Clique em Iniciar Instalação no topo esquerdo e veja a mágica acontecer !

Prontinho! Este arquivo é um canivete suíço de infraestrutura Linux. Se você seguir esses passos, terá o entendimento completo de como os blocos de boot se conversam em baixo nível.

#!/usr/bin/env bash
set -e
# ==============================================================================
# ⚙️ PARÂMETROS DE CONFIGURAÇÃO
# ==============================================================================
USB_REAL=false # 'true' para gravar em pendrive físico, 'false' para criar arquivo .img
TARGET_DEV="/dev/sdb" # Usado apenas se USB_REAL=true (CUIDADO: APAGA TUDO NO DISCO)
IMG_FILE="pendrive.img" # Nome da imagem se USB_REAL=false
IMG_SIZE_MB=30000 # Tamanho total da imagem em MB (ex: 30000 = ~30GB)
EXFAT_SIZE="+20G" # Tamanho da partição 1 (exFAT). Ex: "+10G", "+20G", ou "+500M"
LUKS_PASSWORD="root" # Senha padrão do contêiner LUKS2
ROOT_PASSWORD="root" # Senha da conta root do Debian
# ==============================================================================
if [ "$EUID" -ne 0 ]; then
echo "Execute este script como root (sudo)."
exit 1
fi
sudo apt update && sudo apt install gdisk exfatprogs syslinux-common syslinux extlinux grub-pc-bin \
qemu-system-x86 qemu-utils libvirt-daemon-system libvirt-clients virt-manager osinfo-db ovmf debootstrap -y
sudo usermod -aG libvirt $USER || true
sudo usermod -aG kvm $USER || true
sudo systemctl enable --now libvirtd || true
if [ "$USB_REAL" = true ]; then
DISK_DEV="$TARGET_DEV"
PART_PREFIX=""
if [[ "$DISK_DEV" =~ "nvme" ]] || [[ "$DISK_DEV" =~ "mmcblk" ]]; then
PART_PREFIX="p"
fi
echo "⚠️ Gravando diretamente no dispositivo físico: $DISK_DEV"
else
dd if=/dev/zero of="$IMG_FILE" bs=1M count="$IMG_SIZE_MB" status=progress
DISK_DEV=$(sudo losetup -f --show -P "$IMG_FILE")
PART_PREFIX="p"
echo "📦 Imagem criada e associada ao dispositivo loop: $DISK_DEV"
fi
P1="${DISK_DEV}${PART_PREFIX}1"
P2="${DISK_DEV}${PART_PREFIX}2"
P3="${DISK_DEV}${PART_PREFIX}3"
P4="${DISK_DEV}${PART_PREFIX}4"
sgdisk -Z "$DISK_DEV"
sgdisk -n 1:0:"$EXFAT_SIZE" -t 1:0700 -c 1:"DADOS_USB" "$DISK_DEV"
sgdisk -n 2:0:+2M -t 2:ef02 -c 2:"BIOS_BOOT" "$DISK_DEV"
sgdisk -n 3:0:+500M -t 3:ef00 -c 3:"BOOT_USB" "$DISK_DEV"
sgdisk -n 4:0:0 -t 4:8300 -c 4:"DEBIAN_ROOT" "$DISK_DEV"
sgdisk -h 3 "$DISK_DEV"
sudo mkfs.exfat -n "DADOS_USB" "$P1"
sudo mkfs.vfat -F 32 -n "BOOT_USB" "$P3"
sudo mkdir -p /mnt/usb
sudo mount "$P3" /mnt/usb
sudo grub-install --target=x86_64-efi --efi-directory=/mnt/usb --boot-directory=/mnt/usb/boot --removable
sudo mkdir -p /mnt/usb/boot/grub/i386-pc
sudo cp /usr/lib/grub/i386-pc/*.mod /mnt/usb/boot/grub/i386-pc/
sudo cp /usr/lib/grub/i386-pc/*.lst /mnt/usb/boot/grub/i386-pc/
sudo grub-mkimage -O i386-pc -o /mnt/usb/boot/grub/core.img -p '(hd0,gpt3)/boot/grub' \
biosdisk part_msdos part_gpt fat exfat ext2 btrfs \
crypto cryptodisk luks2 gcry_rijndael gcry_sha256 gzio test normal
sudo cat /usr/lib/grub/i386-pc/lnxboot.img /mnt/usb/boot/grub/core.img | sudo tee /mnt/usb/boot/grub/g2ldr > /dev/null
sudo dd bs=440 count=1 conv=notrunc if=/usr/lib/syslinux/mbr/mbr.bin of="$DISK_DEV"
sudo mkdir -p /mnt/usb/boot/syslinux
if [ "$USB_REAL" = true ]; then
sudo syslinux --install "$P3"
else
sudo extlinux --install /mnt/usb/boot/syslinux
sudo ln -sf extlinux.conf /mnt/usb/boot/syslinux/syslinux.cfg
fi
sudo cp /usr/lib/syslinux/modules/bios/ldlinux.c32 /mnt/usb/boot/syslinux/
sudo tee /mnt/usb/boot/syslinux/syslinux.cfg << 'EOF'
DEFAULT grub2
LABEL grub2
MENU LABEL Carregar GRUB2 Hibrido via Syslinux
KERNEL /boot/grub/g2ldr
EOF
echo -n "$LUKS_PASSWORD" | sudo cryptsetup luksFormat --type luks2 --pbkdf pbkdf2 "$P4" -
echo -n "$LUKS_PASSWORD" | sudo cryptsetup open "$P4" debian_root -
sudo mkfs.btrfs -L "DEBIAN_LUKS" /dev/mapper/debian_root
sudo mkdir -p /mnt/btrfs
sudo mount /dev/mapper/debian_root /mnt/btrfs
sudo btrfs subvolume create /mnt/btrfs/light
sudo umount /mnt/btrfs
sudo mkdir -p /mnt/debian
sudo mount -o subvol=light /dev/mapper/debian_root /mnt/debian
sudo debootstrap --arch amd64 trixie /mnt/debian http://deb.debian.org/debian/
for i in /dev /dev/pts /proc /sys /run; do sudo mount --bind $i /mnt/debian$i; done
UUID_LUKS=$(sudo blkid -s UUID -o value "$P4")
sudo chroot /mnt/debian /bin/bash -c "
cat << 'EOF' > /etc/apt/sources.list
deb http://deb.debian.org/debian/ trixie main contrib non-free non-free-firmware
deb http://deb.debian.org/debian/ trixie-updates main contrib non-free non-free-firmware
deb http://security.debian.org/debian-security trixie-security main contrib non-free non-free-firmware
EOF
apt update
apt install linux-image-amd64 cryptsetup-initramfs btrfs-progs locales -y
dpkg-reconfigure --frontend=noninteractive locales
echo 'root:$ROOT_PASSWORD' | chpasswd
cat << 'EOF' > /etc/fstab
/dev/mapper/debian_root / btrfs defaults,subvol=light 0 1
EOF
echo \"debian_root UUID=$UUID_LUKS none luks,initramfs\" > /etc/crypttab
echo \"CRYPTSETUP=y\" >> /etc/cryptsetup-initramfs/conf-hook
echo \"KEYFILE_PATTERN=\" >> /etc/cryptsetup-initramfs/conf-hook
update-initramfs -u -k all
"
sudo mkdir -p /mnt/usb/boot/
sudo cp /mnt/debian/boot/vmlinuz-* /mnt/usb/boot/vmlinuz
sudo cp /mnt/debian/boot/initrd.img-* /mnt/usb/boot/initrd.img
sudo tee /mnt/usb/boot/grub/grub.cfg << EOF
insmod luks2
insmod cryptodisk
insmod btrfs
insmod gzio
insmod part_gpt
cryptomount -a
menuentry "Debian Trixie Completo (Subvol: light)" {
set root=(crypto0)
linux /light/vmlinuz root=/dev/mapper/debian_root cryptdevice=UUID=$UUID_LUKS:debian_root rootflags=subvol=light ro quiet splash
initrd /light/initrd.img
}
EOF
sudo umount /mnt/debian/dev/pts /mnt/debian/dev /mnt/debian/proc /mnt/debian/sys /mnt/debian/run || true
sudo umount /mnt/debian
sudo umount /mnt/usb
sudo cryptsetup close debian_root
if [ "$USB_REAL" = false ]; then
sudo losetup -d "$DISK_DEV"
fi
echo "✅ Processo concluído com sucesso!"
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment