DebianKernelBuild

🐧 ALSYUNDAWY Linux Kernel DEB Builder

Production-grade shell script to download, verify, configure, build, and optionally install upstream vanilla Linux kernel Debian packages — fully automated, VM-aware, and security-hardened.

✨ Overview

This script builds an upstream vanilla Linux kernel directly from kernel.org into Debian packages using the in-tree Kbuild target make bindeb-pkg. It handles the entire lifecycle — from downloading and cryptographically verifying the source tarball to configuring, compiling, packaging, and installing the resulting .deb files.

Designed for Debian, Ubuntu, Proxmox VE, and all Debian-based distributions.

🚀 Key Features

🔐 Security and Integrity

OpenPGP signature verification of kernel.org tarballs before extraction using WKD-imported developer keys (Torvalds, Kroah-Hartman, Levin)
Hardened GPG invocation with --no-auto-key-import and --no-auto-key-retrieve to prevent silent key injection
Debian certificate sanitization for vanilla upstream sources (SYSTEM_TRUSTED_KEYS, SYSTEM_REVOCATION_KEYS, MODULE_SIG_KEY)
Input validation with regex-based kernel version checks to prevent path or command injection
Strict Bash mode (set -Eeuo pipefail) with ERR, INT, and TERM signal traps
Path canonicalization via readlink -f to prevent symlink-based path traversal

⚙️ Build Pipeline

Isolated build directory per kernel version and timestamp — no cross-contamination between builds
Flexible config seeding: seed from running kernel (/boot/config-*), defconfig, localmodconfig, or none
Interactive and non-interactive modes: menuconfig, nconfig, oldconfig, olddefconfig, or skip entirely
Debug info control: disabled by default to dramatically reduce build time and package size
Parallel compilation with configurable job count (defaults to nproc)
Custom versioning: set LOCALVERSION suffix and KDEB_PKGVERSION override
Release-candidate support: versions like 6.15-rc7 automatically use kernel.org /testing directory

🖥️ VM Guest Optimization

Automatically detects the hypervisor at runtime using systemd-detect-virt and DMI/SMBIOS data, then applies hypervisor-specific kernel configuration:

Hypervisor	Detection	Kernel Options Enabled
KVM / QEMU / Proxmox	`kvm`, `qemu`, `bochs`, `proxmox`	Full VirtIO stack: `virtio-pci`, `virtio-blk`, `virtio-scsi`, `virtio-net`, `virtio-balloon`, `virtio-console`, `virtio-input`, `virtio-rng`, `virtio-crypto`, `virtio-vsock`, `virtio-fs`, `9p`, `net-failover`
VMware	`vmware`	`VMXNET3`, `PVSCSI`, `VMware Balloon`, `VMCI`, `VMCI vsock`, `vmwgfx`, `vmmouse`
Generic VM	`virtualbox`, `xen`, `microsoft`	`HYPERVISOR_GUEST`, `PARAVIRT`, `PARAVIRT_CLOCK`, `HIGH_RES_TIMERS`, `PCI_MSI`, `VSOCKETS`

Driver mode control: choose between loadable module or builtin for paravirtual drivers
Guest tools auto-install: optionally installs and enables qemu-guest-agent or open-vm-tools

📦 Package Management

Smart package discovery from actual build artifacts (no fragile filename globs)
Automatic dependency repair with apt-get -f install fallback after dpkg -i
GRUB bootloader refresh via update-grub after successful installation
Selective installation: install linux-image + linux-headers by default, optionally include linux-libc-dev
Safe cleanup: removes source tree and archives after build while preserving all generated .deb packages

🧪 Dry-Run Mode

Validate all inputs, paths, and environment configuration without making any system changes:

sudo DRY_RUN=1 ./debian_kernel_build.sh 6.12.93

📋 Requirements

OS: Debian, Ubuntu, Proxmox VE, or any Debian-based distribution
Shell: Bash 5.0+
Privileges: Root access (sudo)
Network: Internet access to download kernel sources from cdn.kernel.org
Disk space: At least 20–30 GB free (kernel source + build artifacts)
RAM: Minimum 2 GB, recommended 4 GB+ for parallel builds

All build dependencies are installed automatically by the script:

bc binutils bison build-essential ca-certificates cpio dirmngr dpkg-dev fakeroot flex git gnupg kmod libelf-dev libncurses-dev libssl-dev openssl paxctl perl python3 wget xz-utils zstd

Optional: dwarves (pahole) · lz4 · liblz4-tool

📖 Quick Start — Step by Step

This guide walks you through the entire process. No prior kernel-building experience is required.

Step 1 — Download the Script

Open a terminal on your Debian-based system and run:

wget https://raw.githubusercontent.com/alsyundawy/DebianKernelBuild/master/debian_kernel_build.sh
chmod +x debian_kernel_build.sh

Step 2 — Choose Your Kernel Version

Visit kernel.org to find the latest stable version (e.g., 6.12.93). You can also use release candidates like 6.15-rc7.

Step 3 — Run the Build

Run the script with sudo and pass the kernel version as the argument:

sudo ./debian_kernel_build.sh 6.12.93

The script will automatically:

Install all required build dependencies via APT (you do not need to install anything manually)
Detect your VM hypervisor (KVM, VMware, etc.) if you are running inside a virtual machine
Install VM guest tools (qemu-guest-agent or open-vm-tools) when a supported hypervisor is detected
Download the kernel source tarball from cdn.kernel.org over HTTPS
Verify the OpenPGP signature to ensure the source has not been tampered with
Extract the source tree into an isolated, timestamped build directory
Seed .config from your currently running kernel (/boot/config-*)
Open menuconfig for you to review and customize kernel options — just save and exit when done
Sanitize the config (disable debug info, clear Debian cert paths, apply VM optimizations)
Compile the kernel using all available CPU cores (make -j$(nproc) bindeb-pkg)
Install the generated .deb packages (linux-image and linux-headers)
Refresh the GRUB bootloader so the new kernel appears in the boot menu
Clean up the source tree and archives (the .deb packages are preserved)

Step 4 — Reboot

sudo reboot

Step 5 — Verify

After rebooting, confirm the new kernel is active:

uname -r

You should see the version you just built (e.g., 6.12.93).

💡 Usage Examples

Basic Usage

# Standard interactive build with menuconfig
sudo ./debian_kernel_build.sh 6.12.93

Non-Interactive / Automation

# Fully non-interactive build — ideal for CI pipelines or scripted deployments
sudo CONFIG_MODE=olddefconfig INSTALL_AFTER_BUILD=0 ./debian_kernel_build.sh 6.12.93

VM Guest Builds

# VMware guest with modular paravirtual drivers
sudo VM_GUEST_OPTIMIZE=vmware VM_DRIVER_MODE=module ./debian_kernel_build.sh 6.12.93

# KVM/Proxmox guest with built-in drivers and custom kernel suffix
sudo VM_GUEST_OPTIMIZE=kvm VM_DRIVER_MODE=builtin LOCALVERSION=-pvefast ./debian_kernel_build.sh 6.12.93

Release Candidate Kernels

# Build a release candidate kernel (automatically uses kernel.org /testing directory)
sudo ./debian_kernel_build.sh 6.15-rc7

Build Only (No Install)

# Build packages but do not install them, and keep the source tree
sudo INSTALL_AFTER_BUILD=0 CLEANUP_SOURCE=0 ./debian_kernel_build.sh 6.12.93

Testing and Debugging

# Skip OpenPGP verification (use only for emergency testing)
sudo VERIFY_TARBALL=0 ./debian_kernel_build.sh 6.12.93

# Dry-run — validate inputs and environment without making any changes
sudo DRY_RUN=1 ./debian_kernel_build.sh 6.12.93

# Build with debug symbols enabled (for crash analysis, kgdb, BTF, SystemTap)
sudo DISABLE_DEBUG_INFO=0 ./debian_kernel_build.sh 6.12.93

Custom Branding

# Add a custom suffix to the kernel version string
sudo LOCALVERSION=-alsyundawy ./debian_kernel_build.sh 6.12.93

# Override the Debian package version
sudo KDEB_PKGVERSION=1.0-custom ./debian_kernel_build.sh 6.12.93

🔧 Environment Options

All behavior is controlled through environment variables. Every option has a sensible default — you only need to set the ones you want to change.

Build Configuration

Variable	Default	Description
`KERNEL_WORKDIR`	`/opt/linux`	Base directory for isolated build trees
`JOBS`	`$(nproc)`	Number of parallel `make` jobs
`LOCALVERSION`	(empty)	Custom kernel version suffix (e.g., `-alsyundawy`)
`KDEB_PKGVERSION`	(empty)	Override the Debian package version string

Kernel Configuration

Variable	Default	Description
`CONFIG_SEED`	`running`	Initial `.config` source: `running` · `defconfig` · `localmodconfig` · `none`
`CONFIG_MODE`	`menuconfig`	Configuration frontend: `menuconfig` · `nconfig` · `oldconfig` · `olddefconfig` · `none`
`DISABLE_DEBUG_INFO`	`1`	Disable `CONFIG_DEBUG_INFO` and BTF to reduce build time and size
`SANITIZE_DEBIAN_CERTS`	`1`	Clear Debian-specific certificate paths for vanilla sources

Security and Verification

Variable	Default	Description
`VERIFY_TARBALL`	`1`	Verify OpenPGP signature of the kernel tarball before extraction
`GPG_AUTO_LOCATE_KEYS`	`1`	Auto-import kernel.org developer keys via WKD

VM Guest Optimization

Variable	Default	Description
`VM_GUEST_OPTIMIZE`	`auto`	VM detection mode: `auto` · `kvm` · `qemu` · `proxmox` · `vmware` · `generic` · `none`
`VM_DRIVER_MODE`	`module`	Paravirtual driver linkage: `module` (loadable) · `builtin` (compiled-in)
`INSTALL_VM_GUEST_TOOLS`	`1`	Auto-install `qemu-guest-agent` or `open-vm-tools` when a hypervisor is detected

Installation and Cleanup

Variable	Default	Description
`INSTALL_AFTER_BUILD`	`1`	Automatically install `linux-image` and `linux-headers` after build
`INSTALL_LIBC_DEV`	`0`	Also install `linux-libc-dev` from this build
`REFRESH_BOOTLOADER`	`1`	Run `update-grub` after successful package installation
`CLEANUP_SOURCE`	`1`	Remove source tree, tarball, and signature after build
`DRY_RUN`	`0`	Validate all inputs and environment without making any system changes

🔄 Build Pipeline Flow

┌─────────────────┐
│  Validate Input  │  Version format, env vars, boolean checks
└────────┬────────┘
         │
┌────────▼────────┐
│  Install Deps    │  APT packages, optional tools (dwarves, lz4)
└────────┬────────┘
         │
┌────────▼────────┐
│  Detect VM       │  systemd-detect-virt + DMI/SMBIOS probing
└────────┬────────┘
         │
┌────────▼────────┐
│  Guest Tools     │  qemu-guest-agent / open-vm-tools (optional)
└────────┬────────┘
         │
┌────────▼────────┐
│  Download        │  wget from cdn.kernel.org (HTTPS, timeout, retries)
└────────┬────────┘
         │
┌────────▼────────┐
│  Verify (GPG)    │  OpenPGP signature via detached .tar.sign
└────────┬────────┘
         │
┌────────▼────────┐
│  Extract         │  tar -xf into isolated build directory
└────────┬────────┘
         │
┌────────▼────────┐
│  Seed .config    │  running kernel / defconfig / localmodconfig
└────────┬────────┘
         │
┌────────▼────────┐
│  Config Frontend │  menuconfig / nconfig / oldconfig / olddefconfig
└────────┬────────┘
         │
┌────────▼────────┐
│  Sanitize Config │  Certs, debug info, VM options, olddefconfig sync
└────────┬────────┘
         │
┌────────▼────────┐
│  Build (bindeb)  │  make -jN bindeb-pkg → .deb packages
└────────┬────────┘
         │
┌────────▼────────┐
│  Install         │  dpkg -i with auto dependency repair
└────────┬────────┘
         │
┌────────▼────────┐
│  Cleanup         │  Remove source, preserve .deb packages
└────────┬────────┘
         │
┌────────▼────────┐
│  Summary         │  List packages, boot notes, VM recommendations
└─────────────────┘

🗑️ Uninstall

The custom kernel is installed as standard Debian packages. You can remove it at any time using APT:

# List all installed kernel packages
dpkg -l | grep linux-image

# Remove a specific kernel version
sudo apt remove --purge linux-image-6.12.93
sudo apt remove --purge linux-headers-6.12.93

# Update the bootloader to remove stale entries
sudo update-grub

⚠️ Important Notes

Always verify the GRUB bootloader entry before rebooting production systems.
The script does not run kexec automatically. Use a controlled reboot to activate the new kernel.
For Proxmox/QEMU VMs: configure VirtIO SCSI (or VirtIO Block) and VirtIO NIC on the hypervisor side for optimal performance with the built kernel.
For VMware VMs: use VMXNET3 for networking and PVSCSI for high-I/O virtual disks.
Debug symbols: set DISABLE_DEBUG_INFO=0 if you need crash analysis, kgdb, BTF, or SystemTap workflows.
Build time: a full kernel build typically takes 15–60 minutes depending on CPU speed, number of cores, and kernel configuration. Setting CONFIG_MODE=olddefconfig and DISABLE_DEBUG_INFO=1 (the default) produces the fastest builds.

🛡️ Code Quality

This script adheres to professional shell scripting standards:

✅ ShellCheck compliant — zero warnings at -S style severity level
✅ Strict Bash mode — set -Eeuo pipefail with ERR, INT, and TERM traps
✅ Locale-safe — LC_ALL=C for reproducible text parsing across environments
✅ Secure defaults — GPG verification, HTTPS-only downloads, path canonicalization
✅ Clean code — modular functions, descriptive logging, comprehensive input validation

📝 Changelog

`2026.06.14-r5` — Security Audit and Hardening

Performed a full end-to-end code audit covering logic, security, and ShellCheck compliance.
Fixed ShellCheck SC2155: split local declaration and command substitution in seed_kernel_config to avoid masking return values.
Hardened GPG invocation with --no-auto-key-import to prevent silent key injection from untrusted sources during OpenPGP signature verification.
Added wget --timeout=60 and --tries=3 to prevent indefinite hangs on slow or unreachable network endpoints during kernel tarball and signature downloads.
Fixed on_error trap exit code: when the ERR trap fires with exit_code=0 (edge case in complex pipelines), the trap now defaults to exit 1 to prevent silent success.
Restored ERR trap alongside errexit in run_localmodconfig by using set -Ee instead of set -e to keep the error trap active after re-enabling strict mode.
Added INT and TERM signal traps for graceful cleanup of the temporary GPG home directory when the script is interrupted by Ctrl-C or system signals.
Added LC_ALL=C export early in initialization for reproducible text parsing across different locale environments during build operations.
Canonicalized KERNEL_WORKDIR using readlink -f (when available) to resolve symbolic links and prevent path traversal issues in build directory setup.
Removed wget -c (continue) flag from signature download to prevent partial or corrupt file reuse during OpenPGP verification.
Added wget --no-hsts flag to avoid unnecessary HSTS database writes during kernel downloads.

`2026.06.14-r4` — VM Optimization Audit

Audited the full script from start to finish after adding VM optimization.
Fixed localmodconfig handling so it remains safe under errexit and pipefail.
Added kmod and python3 to the required dependency set for modern kernel package builds.
Changed core VirtIO symbols to built-in enablement while keeping concrete device drivers controlled by VM_DRIVER_MODE=module|builtin.
Added VIRTIO_MENU and SCSI_LOWLEVEL enablement to improve dependency resolution for VirtIO and VMware SCSI drivers.
Added optional REFRESH_BOOTLOADER=1 to refresh GRUB when update-grub exists after successful package installation.
Added DRY_RUN=1 support for syntax, path, and argument validation without making system changes.
Kept security sane: no mitigations=off, no unsafe kernel command-line tweaks, and no global scheduler or sysctl tuning.

`2026.06.14-r3` — VM Guest Detection

Added automatic VM guest detection for KVM/QEMU/Proxmox and VMware using systemd-detect-virt and DMI/SMBIOS data.
Added safe VM-focused kernel configuration patching for responsiveness and lower virtual I/O overhead.
Added VirtIO stack optimization for Proxmox/QEMU guests: virtio-pci, virtio-blk, virtio-scsi, virtio-net, virtio-balloon, virtio-console, virtio-rng, virtio-vsock, virtio-fs, 9p over virtio, and net-failover.
Added VMware stack optimization: vmxnet3, vmw_pvscsi, vmw_balloon, vmw_vmci, VMware VMCI vsock transport, vmwgfx, and vmmouse.
Added optional VM driver mode control through VM_DRIVER_MODE=module|builtin.
Added optional runtime guest tools installation through INSTALL_VM_GUEST_TOOLS.

`2026.06.14-r2` — Internationalization and RC Support

Kept the working structure from the previous corrected version.
Converted all comments, usage text, log messages, warnings, and errors to English as requested.
Added release-candidate URL handling: versions containing -rcN use the kernel.org /testing directory automatically.
Added stronger KERNEL_WORKDIR validation to avoid accidental root-level or empty-directory operations.
Added dirmngr to dependencies to improve GnuPG WKD/key discovery reliability.
Moved config sanitization after the selected config frontend so the final build config is always safe unless explicitly disabled by environment.
Added a safe localmodconfig pipeline wrapper compatible with pipefail.
Preserved generated .deb packages while making cleanup path-scoped and safe.

`2026.06.14-r1` — Initial Hardened Release

Added strict mode: set -Eeuo pipefail and an ERR trap.
Added kernel version validation to prevent path or command injection.
Added a broader Debian build dependency set: flex, bison, dwarves/pahole, dpkg-dev, ca-certificates, gnupg, wget, zstd, and lz4 fallback support.
Added OpenPGP verification for kernel.org tarballs before extraction.
Replaced global /opt/linux cleanup with an isolated build directory per kernel version and timestamp.
Replaced fragile dpkg filename globs with package discovery from actual build artifacts.
Added environment-variable controls without removing the original workflow.
Quoted all variable expansions and used array-safe apt/dpkg invocation.

👤 Author — HARRY DS ALSYUNDAWY

🌐 Website: alsyundawy.com
📧 Email: alsyundawy@gmail.com
💬 WhatsApp: +62 856-8515-1212
🐙 GitHub: github.com/alsyundawy

📄 License

This project is licensed under the GNU General Public License. See the LICENSE file for details.

This site is open source. Improve this page.